package.json

简介

• 项目核心，其中包含当前项目所需要的各种模块，以及项目的配置信息（比如名称、版本、许可证等）。

• 当运行npm install命令的时候，会根据package.json文件中的配置自动下载所需的模块，也就是配置项目所需的运行和开发环境。

作用

• 配置和描述如何与程序交互和运行的中心
• package.json 文件使 npm 可以启动你的项目、运行脚本、安装依赖项、发布到 NPM 注册表以及许多其他有用的任务

必需属性

name

• name是 package(包)的名称。名称的第一部分(如@scope/是可选的,用作名称空间)。当我们的包发布到 NPM 网站，其他人才能通过搜索name来安装使用

{"name": "@scope/name"}

• 最好取简短而语义化的值
• 不能以,.开头
• 不能有大写字母/空格/下滑线!
• 不能和 NPM 网站中已有的包名字重名！

version

• package(包)的版本

{"version": "2.7.7",}

version 具体体现为：:“x.y.z”

• 修复 bug,小改动，增加 z
• 增加了新特性，但仍能向后兼容，增加 y
• 有很大的改动，无法向后兼容,增加 x

语义化规范

描述信息

description

描述

keywords

• 项目关键词

{ "keywords": ["ant","component","vue"]}

author, contributors（作者 贡献者）

  {"author": "zhangsan","contributors": ["zhangsan","lisi"]}

homepage

• 项目主页 url,默认值为/

{"homepage": "https://ant.design"}

加载资源的根路径

repository

• 储存库，代码的存放仓库地址

bugs

• bug 提交地址

{"bugs": {"url":"https://github.com"}}

依赖配置

dependencies

• 应用依赖，或业务依赖/生产环境依赖，最常用的依赖包管理对象，用于指定应用依赖的外部包
• 执行项目的 npm run build 时需要的依赖包
• 不要把开发环境的依赖包放在这里

devDependencies

• 开发环境依赖包，即执行项目的 npm start 时需要的依赖包

peerDependencies

• 当前package中使用的依赖
• 提示宿主环境去安装满足插件 peerDependencies 所指定依赖的包
• 解决插件与所依赖包不一致的问题

optionalDependencies

• 在找不到包或者安装包失败时，npm仍然能够继续运行，则可以将该包放在optionalDependencies对象中

bundledDependencies

• 指定一些模块，这些模块将在这个包发布时被一起打包

engines

• 指明了该模块运行的平台，engines只是起一个说明的作用
• 当我们维护一些旧项目时，可能对npm包的版本或者Node版本有特殊要求，如果不满足条件就可能无法将项目跑起来。为了让项目开箱即用，可以在engines字段中说明具体的版本号

脚本配置

scripts

• scripts 是 package.json中内置的脚本入口，是key-value键值对配置，key为可运行的命令，可以通过 npm run 来执行命令。除了运行基本的scripts命令，还可以结合pre和post完成前置和后续操作。先来看一组scripts：

"scripts": { 	
  "dev": "node index.js",  
  "start": "icejs start",
   "build": "icejs build",
   "lint": "npm run eslint && npm run stylelint",
   "eslint": "eslint --cache --ext .js,.jsx,.ts,.tsx ./",
} 

• 这些脚本是命令行应用程序。可以通过调用 npm run XXX 或 yarn XXX 来运行它们，其中 XXX 是命令的名称。 例如：npm run start，启动项目。我们可以为命令使用任何的名称，脚本也可以是任何操作。使用好该字段可以大大的提升开发效率

config

{"config": {
    "port": "8000"
}}

• 当执行npm start命令，就会引用 npm_package_config_port 环境变量，
• 如上面的配置npm start时，就会通过端口8000启动
• 可通过执行如 npm config set foo:port 8001 来覆盖config配置

文件&目录

main

• 用来指定加载的入口文件

{"main": "lib/index.js"}

• 假如项目为npm 包，当用户安装后，require('my-module') 返回的是 main 字段中所列出文件的 module.exports 属性。
• 不指定main字段时，默认值是模块根目录下面的 index.js 文件。

module

• 定义 npm 包的 ESM 规范的入口文件
• 用于指向 ES 版本的库/包,一般指定为 webpack/rollup 打包 ES 版本后的路径

browser

• 定义 npm 包在 browser 环境下的入口文件

bin

• 用来指定加载的入口文件
• 用于将某些可执行 Javascript 文件公开给父包的字段

files 文件

• 将软件包作为依赖项安装时要包括的条目，默认值为[“*”]，包括所有文件

把打包后的代码发布到 NPM 仓库：
{"files": ["dist/**/*", "lib/**/*"]}

man

• man 命令是 Linux 中的帮助指令，通过该指令可以查看 Linux 中的指令帮助、配置文件帮助和编程帮助等信息

directories

• 用来规范项目的目录
• 模块目录下除了必须包含包项目描述文件 package.json 以外，还需要包含以下目录：
• • bin ：存放可执行二进制文件的目录
• • lib ：存放js代码的目录
• • doc ：存放文档的目录
• • test ：存放单元测试用例代码的目录

发布配置

private

• private字段可以防止我们意外地将私有库发布到npm服务器。将该字段设置为true

preferGlobal

• preferGlobal字段表示当用户不把该模块安装为全局模块时，如果设置为true就会显示警告。它并不会真正的防止用户进行局部的安装，只是对用户进行提示，防止产生误解

publishConfig

• publishConfig配置会在模块发布时生效，用于设置发布时一些配置项的集合。如果不想模块被默认标记为最新，或者不想发布到公共仓库，可以在这里配置tag或仓库地址。更详细的配置可以参考
  npm-config

• 通常情况下，publishConfig会配合private来使用，如果只想让模块发布到特定npm仓库，就可以这样来配置：

"publishConfig": {  
  "tag": "1.1.0",  
  "registry": 
  "https://registry.npmjs.org/",  
  "access": "public" } 

os

• os字段可以让我们设置该npm包可以在什么操作系统使用，不能在什么操作系统使用。如果我们希望开发的npm包只运行在linux，为了避免出现不必要的异常，建议使用Windows系统的用户不要安装它，这时就可以使用os配置：

• "os" ["linux"] // 适用的操作系统

• "os" ["!win32"] // 禁用的操作系统

cpu

• 该配置和OS配置类似，用CPU可以更准确的限制用户的安装环境：

• "cpu" ["x64", "AMD64"] // 适用的cpu "cpu" ["!arm", "!mips"] // 禁用的cpu

• 可以看到，黑名单和白名单的区别就是，黑名单在前面加了一个“!”。

license

• 开源协议，模块权限以及模块限制

{"license": "MIT"}

• MIT 约束最少
• GPL 约束最多

第三方配置

package.json 文件还可以承载命令特有的配置，例如 Babel、ESLint 等。它们每个都有特有的属性

typings

typings字段用来指定TypeScript的入口文件：

{"typings": "types/index.d.ts"}

该字段的作用和main配置相同。

eslintConfig

eslint的配置可以写在单独的配置文件.eslintrc.json 中，也可以写在package.json文件的eslintConfig配置项中。

"eslintConfig": {   
  "root": true,     
  "env": {"node": true},       
  "extends": [
    "plugin:vue/essential",      
    "eslint:recommended"       
  ],     
   "rules": {},     
   "parserOptions": {       
     "parser": "babel-eslint"   
   }, 
}

babel

babel用来指定Babel的编译配置，代码如下：

"babel": { 	
  "presets": ["@babel/preset-env"], 	
  "plugins": [...] 
 } 

unpkg

使用该字段可以让 npm 上所有的文件都开启 cdn 服务，该CND服务由unpkg提供：

"unpkg": "dist/vue.js"

lint-staged

lint-staged是一个在Git暂存文件上运行linters的工具，配置后每次修改一个文件即可给所有文件执行一次lint检查，通常配合gitHooks一起使用。

{"lint-staged": { 	
  "*.js": [   
    "eslint --fix",     
    "git add"  
  ] 
 }}

使用lint-staged时，每次提交代码只会检查当前改动的文件。

gitHooks

gitHooks用来定义一个钩子，在提交（commit）之前执行ESlint检查。在执行lint命令后，会自动修复暂存区的文件。修复之后的文件并不会存储在暂存区，所以需要用git add命令将修复后的文件重新加入暂存区。在执行pre-commit命令之后，如果没有错误，就会执行git commit命令：

"gitHooks": {"pre-commit": "lint-staged" }
这里就是配合上面的lint-staged来进行代码的检查操作。

browserslist

browserslist字段用来告知支持哪些浏览器及版本。Babel、Autoprefixer 和其他工具会用到它，以将所需的 polyfill 和 fallback 添加到目标浏览器。比如最上面的例子中的该字段值：

"browserslist": {  
  "production": [   
    ">0.2%",    
    "not dead",    
    "not op_mini all"  
  ],   
   "development": [  
     "last 1 chrome version",   
     "last 1 firefox version",    
     "last 1 safari version"  
   ]
}

package.json 与 package-lock.json 的关系

• package.json 用来描述项目及项目所依赖的模块信息。

• package-lock.json 它会在 npm 更改 node_modules 目录树 或者 package.json 时自动生成的 ，它准确的描述了当前项目npm包的依赖树，并且在随后的安装中会根据 package-lock.json 来安装，保证是相同的一个依赖树，不考虑这个过程中是否有某个依赖有小版本的更新。

• 它的产生就是来对整个依赖树进行版本固定的（锁死）。

• 场景：依赖A依赖于依赖C-1.0版本，依赖B依赖于依赖C-2.0版本；而在执行npm install命令的时候，会按照package.json里面的依赖顺序依次解析，因此依赖C-1.0和依赖C-2.0的在文件里的放置顺序会导致node_modules的依赖结构产生变化。而且为了让开发者可以使用最新的依赖包，package.json文件里通常只会锁定大版本（即文件里依赖如果是^1.1.0版本，npm就会去仓库中获取符合1.x.x形式的最新版本），因此某些依赖包小版本更新后，也会造成依赖结构的改变。

• 当我们在一个项目中npm install时候，会自动生成一个package-lock.json文件，和package.json在同一级目录下。package-lock.json记录了项目的一些信息和所依赖的模块。这样在每次安装都会出现相同的结果. 不管你在什么机器上面或什么时候安装。

• 当我们下次再npm install时候，npm 发现如果项目中有 package-lock.json 文件，会根据 package-lock.json 里的内容来处理和安装依赖而不再根据 package.json。

• package-lock.json文件可以保证每次执行npm install后生成的node_modules目录结构一定是完全相同的。

• package-lock.json 文件还有个优点，就是它会缓存每个包的具体版本和下载链接，在后期再去install的时候，就不需要再去远程仓库进行查询操作了，减少了大量网络请求。

npm install 和 npm run 执行后都做了什么？

运行npm install命令的时候会发生什么？

1.npm install命令输入

2.根据package.json包里的依赖去 检查node_modules目录下是否存在指定的依赖

3.如果已经存在则不必重新安装 ，若不存在，继续下面的步骤

4.向 registry（本地电脑的.npmrc文件里有对应的配置地址）查询模块压缩包的网址

5.下载压缩包，存放到根目录里的.npm目录里

6.解压压缩包到当前项目的node_modules目录中。

补充：几种不同的install命令下载方式

npm install xxx #（XXX是某依赖包）安装依赖模块至项目node_modules目录下，不会修改package.json文件里的内容

npm install -g xxx #安装依赖模块到全局（而不是项目node_modules目录下），不会将该依赖模块写到package.json文件里的dependencies和devDependencies字段里

npm install --save xxx #安装依赖模块到项目node_modules目录下，并将依赖写入到package.json文件里的dependencies字段中；该依赖是开发和生产环境里都需要的

npm install --save-dev xxx #安装依赖模块到项目node_modules目录下，并将依赖写入到package.json文件里的devDependencies字段中，开发环境

npm run xxx 到底执行了什么呢？

Q：npm run xxx到底执行了什么？

A：去package.json文件里找scripts里找对应的参数xxx ，然后执行xxx的命令，例如启动react项目 npm run start的时候，实际上是执行了 icejs start 这条命令。为什么不直接执行 icejs start，因为直接执行会报错，操作系统中没有存在 icejs 这一条命令。

Q：为什么执行 npm run start 的时候，这样它能成功，不报指令错误呢？

A：我们在安装依赖的时候，是通过npm i xxx来执行的，我们在安装一条命令 例如：npm i @ice.js，npm在安装这个依赖的时候就会在node-modules/.bin/ 目录下创建好 icejs 为名的几个可执行文件，

.bin 目录，这个目录下不是任何一个npm包，这是一个软链接，打开文件可以看到文件顶部写着#!/bin/sh，表示这是一个脚本。由此我们可以知道，当使用 npm run start 执行 icejs start 时，虽然没有安装 icejs 的全局命令，但是 npm 会到 ./node_modules/.bin 中找到 icejs 文件作为 脚本来执行，则相当于执行了 ./node_modules/.bin/ icejs start.

Q：.bin 目录下的文件表示软连接，那这个bin目录下的那些软连接文件是哪里来的呢？它又是怎么知道这条软连接是执行哪里的呢？

A：可以看到，它存在项目最外层的package-lock.json文件中

从 package-lock.json 中可知，当我们npm i 整个新建的vue项目的时候，npm 将 bin/ice-cli.js 作为 bin 声明了。

所以在 npm install 时，npm 读到该配置后，就将该文件软链接到 ./node_modules/.bin 目录下，而 npm 会自动把node_modules/.bin加入$PATH变量中，这样就可以直接作为命令运行依赖程序和开发依赖程序，不用全局安装了。

假如我们在安装包时，使用 npm install -g xxx 来安装，那么会将其中的 bin 文件加入到全局，比如 create-react-app 和 vue-cli ，在全局安装后，就可以直接使用如 vue-cli projectName 这样的命令来创建项目了。

也就是说，npm i 的时候，npm 就帮我们把这种软连接配置好了，其实这种软连接相当于一种映射，执行npm run xxx 的时候，就会到 node_modules/bin中找对应的映射文件，然后再找到相应的js文件来执行。

版权声明

原作者CSDN博主「汤姆丁1111」，遵循CC 4.0 BY-SA版权协议

原文链接：blog.csdn.net/weixin_5384…

原作者简书博主 「ikonan」 著作权归作者所有

原文链接：www.jianshu.com/p/c86d511d9…