深度解析package.json

package.json文件解析（author:慧敏）

每个项目的根目录下一般都会有一个package.json文件，这个文件定义了当前项目所需要的各种模块，以及项目的配置信息（比如名称、版本、许可证等）。

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

一、必须属性

package.json中最重要的两个字段就是name和version，它们都是必须的，如果没有，就无法正常执行npm install命令。npm规定package.json文件是由名称和版本号作为唯一标识符的。

1. name name很容易理解，就是项目的名称，它是一个字符串

version
version字段表示该项目包的版本号，它是一个字符串。在每次项目改动后，即将发布时，都要同步的去更改项目的版本号。版本号的使用规范如下：

版本号的命名遵循语义化版本2.0.0规范，格式为：主版本号.次版本号.修订号，通常情况下，修改主版本号是做了大的功能性的改动，修改次版本号是新增了新功能，修改修订号就是修复了一些bug。

二、描述信息

description
description字段用来描述这个项目包，它是一个字符串，可以让其他开发者在 npm 的搜索中发现我们的项目包。
keywords
keywords字段是一个字符串数组，表示这个项目包的关键词。和description一样，都是用来增加项目包的曝光率的。下面是eslint包的描述和关键词：

author
author顾名思义就是作者，表示该项目包的作者. 有两种格式

// 第一种
"author": "DUHUIMIN"
// 第二种
"author": {
  "name" : "DUHUIMIN",
  "email" : "xxxxx@xx.com",
  "url" : "https:xxx"
}

4. contributors

contributors表示该项目包的贡献者，和author不同的是，该字段是一个数组，包含所有的贡献者，它同样有两种写法：

// 第一种
"contributors": [  
  "DU <xxxxx@xx.com> (https://xxx)",   
  "DU <xxxxx@xx.com> (https://xxx)"  
] 
//第二种
"contributors": [  
  { 
   "name" : "DU",   
   "email" : "xxxxx@xx.com",   
   "url" : "https://xxx" 	
  },  
  { 
   "name" : "DU",   
   "email" : "xxxxx@xx.com",   	
   "url" : "https://xxx" 	
  } 
]

5. homepage

homepage就是项目的主页地址了，它是一个字符串。

6. repository

repository表示代码的存放仓库地址，通常有两种书写形式。第一种是字符串形式：

"repository": "https://github.com/facebook/react.git"

除此之外，还可以显式地设置版本控制系统，这时就是对象的形式：

"repository": {  
  "type": "git",   
   "url": "https://github.com/facebook/react.git" 
}

7. bugs

bugs表示项目提交问题的地址，该字段是一个对象，可以添加一个提交问题的地址和反馈的邮箱：

"bugs": {  
  "url" : "https://github.com/facebook/react/issues",  
  "email" : "xxxxx@xx.com" 
}

最常见的bugs就是Github中的issues页面，如上就是react的issues页面地址。

三、依赖配置

通常情况下，我们的项目会依赖一个或者多个外部的依赖包，根据依赖包的不同用途，可以将他们配置在下面的五个属性下：dependencies、devDependencies、peerDependencies、bundledDependencies、optionalDependencies 。下面就来看看每个属性的含义。

1. dependencies

dependencies字段中声明的是项目的生产环境中所必须的依赖包。当使用 npm 或 yarn 安装npm包时，该npm包会被自动插入到此配置项中：

npm install <PACKAGENAME> 
  
yarn add <PACKAGENAME>

当在安装依赖时使用--save参数，也会将新安装的npm包写入dependencies属性。

npm install --save <PACKAGENAME>

该字段的值是一个对象，该对象的各个成员，分别由模块名和对应的版本要求组成，表示依赖的模块及其版本范围。

"dependencies": {   
  "react": "^17.0.2",    
  "react-dom": "^17.0.2",   
  "react-scripts": "4.0.3", 
},

这里每一项配置都是一个键值对（key-value）， key表示模块名称，value表示模块的版本号。版本号遵循主版本号.次版本号.修订号的格式规定：

固定版本： 上面的react-scripts的版本4.0.3就是固定版本，安装时只安装这个指定的版本；
波浪号： 比如~4.0.3，表示安装4.0.x的最新版本（不低于4.0.3），也就是说安装时不会改变主版本号和次版本号；
插入号： 比如上面 react 的版本^17.0.2，表示安装17.x.x的最新版本（不低于17.0.2），也就是说安装时不会改变主版本号。如果主版本号为0，那么插入号和波浪号的行为是一致的；
latest：安装最新的版本。

2. devDependencies

devDependencies中声明的是开发阶段需要的依赖包，如Webpack、Eslint、Babel等，用于辅助开发。它们不同于 dependencies，因为它们只需安装在开发设备上，而无需在生产环境中运行代码。当打包上线时并不需要这些包，所以可以把这些依赖添加到 devDependencies 中，这些依赖依然会在本地指定 npm install 时被安装和管理，但是不会被安装到生产环境中。

当使用 npm 或 yarn 安装软件包时，指定以下参数后，新安装的npm包会被自动插入到此列表中：

npm install --save-dev <PACKAGENAME> yarn add --dev <PACKAGENAME> 
  
"devDependencies": {  
    "ice.js": "^1.0.0",
    "jest": "^24.9.0",
    "react-hooks": "^1.0.1",
}

3. peerDependencies

用于放置当前package中使用的依赖，而且会在引用的项目中会存在的依赖。放在peerDependencies中的依赖不会再当前package中下载，而会使用引用的项目中的依赖。

如果package中放在peerDependencies的依赖，但是项目中不存在依赖，同样会报错。

比如：项目A中存在react，package B是一个基于react的依赖包，package B 就不需要自己安装一份react，因为使用它的项目A必然存在react。

4. optionalDependencies

如果需要在找不到包或者安装包失败时，npm仍然能够继续运行，则可以将该包放在optionalDependencies对象中，optionalDependencies对象中的包会覆盖dependencies中同名的包，所以只需在一个地方进行设置即可。

需要注意，由于optionalDependencies中的依赖可能并为安装成功，所以一定要做异常处理，否则当获取这个依赖时，如果获取不到就会报错。

5. bundledDependencies

上面的几个依赖相关的配置项都是一个对象，而bundledDependencies配置项是一个数组，数组里可以指定一些模块，这些模块将在这个包发布时被一起打包。

需要注意，这个字段数组中的值必须是在dependencies, devDependencies两个里面声明过的包才行。

6. engines

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

"engines": { "node": ">=8.10.3 <12.13.0", "npm": ">=6.9.0" }

需要注意，engines只是起一个说明的作用，即使用户安装的版本不符合要求，也不影响依赖包的安装。

四、脚本配置

1. 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，启动项目。我们可以为命令使用任何的名称，脚本也可以是任何操作。使用好该字段可以大大的提升开发效率。

2. config

config字段用来配置scripts运行时的配置参数，如下所示：

"config": { 	"port": 3000 }

如果运行npm run start，则port字段会映射到npm_package_config_port环境变量中：

console.log(process.env.npm_package_config_port) // 3000

用户可以通过npm config set foo:port 3001 命令来重写port的值。

五、文件&目录

下面来看看package.json中和文件以及目录相关的属性。

1. main

main 字段用来指定加载的入口文件，在 browser 和 Node 环境中都可以使用。如果我们将项目发布为npm包，那么当使用 require 导入npm包时，返回的就是main字段所列出的文件的module.exports 属性。如果不指定该字段，默认是项目根目录下的index.js。如果没找到，就会报错。

该字段的值是一个字符串：

"main": "./src/index.js",

2. browser

browser字段可以定义 npm 包在 browser 环境下的入口文件。如果 npm 包只在 web 端使用，并且严禁在 server 端使用，使用 browser 来定义入口文件。

"browser": "./src/index.js"

3. module

module字段可以定义 npm 包的 ESM 规范的入口文件，browser 环境和 node 环境均可使用。如果 npm 包导出的是 ESM 规范的包，使用 module 来定义入口文件。

"module": "./src/index.mjs",

需要注意，.js 文件是使用 commonJS 规范的语法(require('xxx'))，.mjs 是用 ESM 规范的语法(import 'xxx')。

上面三个的入口入口文件相关的配置是有差别的，特别是在不同的使用场景下。在Web环境中，如果使用loader加载ESM（ES module），那么这三个配置的加载顺序是browser→module→main，如果使用require加载CommonJS模块，则加载的顺序为main→module→browser。

Webpack在进行项目构建时，有一个target选项，默认为Web，即构建Web应用。如果需要编译一些同构项目，如node项目，则只需将webpack.config.js的target选项设置为node进行构建即可。如果再Node环境中加载CommonJS模块，或者ESM，则只有main字段有效。

4. bin

bin字段用来指定各个内部命令对应的可执行文件的位置：

"bin": {   "someTool": "./bin/someTool.js" }

这里，someTool 命令对应的可执行文件为 bin 目录下的 someTool.js，

someTool.js会建立符号链接 node_modules/.bin/someTool。

由于node_modules/.bin/目录会在运行时加入系统的PATH变量，因此在运行npm时，就可以不带路径，直接通过命令来调用这些脚本。因此，下面的写法可以简写：

scripts: {     
  start: './node_modules/bin/someTool.js build' 
} 
// 简写
scripts: 
{ start: 'someTool build' }

所有node_modules/.bin/目录下的命令，都可以用npm run [命令]的格式运行。

上面的配置在package.json包中提供了一个映射到本地文件名的bin字段，之后npm包将链接这个文件到prefix/fix里面，以便全局引入。或者链接到本地的node_modules/.bin/文件中，以便在本项目中使用。

5. files

files配置是一个数组，用来描述当把npm包作为依赖包安装时需要说明的文件列表。当npm包发布时，files指定的文件会被推送到npm服务器中，如果指定的是文件夹，那么该文件夹下面所有的文件都会被提交。

"files": [   
  "LICENSE",     
  "Readme.md",     
  "index.js",     
  "lib/"  ]

如果有不想提交的文件，可以在项目根目录中新建一个.npmignore文件，并在其中说明不需要提交的文件，防止垃圾文件推送到npm上。这个文件的形式和 .gitignore类似。写在这个文件中的文件即便被写在files属性里也会被排除在外。比如可以在该文件中这样写：

# dependencies
/node_modules

# production
/build
/dist
/.ice

# misc
.idea/
.happypack
.DS_Store

npm-debug.log*
yarn-debug.log*
yarn-error.log*

6. man

man 命令是 Linux 中的帮助指令，通过该指令可以查看 Linux 中的指令帮助、配置文件帮助和编程帮助等信息。如果 node.js 模块是一个全局的命令行工具，在 package.json 通过 man 属性可以指定 man 命令查找的文档地址：

"man": [ 
  "./man/npm-access.1", 	
  "./man/npm-audit.1" 
]

man 字段可以指定一个或多个文件, 当执行man {包名}时, 会展现给用户文档内容。

7. directories

directories字段用来规范项目的目录。node.js 模块是基于 CommonJS 模块化规范实现的，需要严格遵循 CommonJS 规范。模块目录下除了必须包含包项目描述文件 package.json 以外，还需要包含以下目录：

bin ：存放可执行二进制文件的目录
lib ：存放js代码的目录
doc ：存放文档的目录
test ：存放单元测试用例代码的目录
...

六、发布配置

下面来看看和npm项目包发布相关的配置。

1. private

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

"private": true

2. preferGlobal

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

"preferGlobal": true

3. publishConfig

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

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

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

4. os

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

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

5. cpu

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

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

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

6. license

license 字段用于指定软件的开源协议，开源协议表述了其他人获得代码后拥有的权利，可以对代码进行何种操作，何种操作又是被禁止的。常见的协议如下：

MIT ：只要用户在项目副本中包含了版权声明和许可声明，他们就可以拿你的代码做任何想做的事情，你也无需承担任何责任。
Apache ：类似于 MIT ，同时还包含了贡献者向用户提供专利授权相关的条款。
GPL ：修改项目代码的用户再次分发源码或二进制代码时，必须公布他的相关修改。

可以这样来声明该字段：

"license": "MIT"

七、第三方配置

package.json 文件还可以承载命令特有的配置，例如 Babel、ESLint 等。它们每个都有特有的属性，例如 eslintConfig、babel 等。它们是命令特有的，可以在相应的命令/项目文档中找到如何使用它们。下面来看几个常用的第三方配置项。

1. typings

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

"typings": "types/index.d.ts",

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

2. eslintConfig

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

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

3. babel

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

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

4. unpkg

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

"unpkg": "dist/vue.js"

5. lint-staged

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

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

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

6. gitHooks

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

"gitHooks": { 	"pre-commit": "lint-staged" }

这里就是配合上面的lint-staged来进行代码的检查操作。

7. 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 来安装，保证是相同的一个依赖树，不考虑这个过程中是否有某个依赖有小版本的更新。

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

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

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

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.

3.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文件来执行。

二：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时候，npm 发现如果项目中有 package-lock.json 文件，会根据 package-lock.json 里的内容来处理和安装依赖而不再根据 package.json。

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

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

posted @ 2022-06-30 15:49 喻佳文阅读(1433) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

喻佳文

深度解析package.json

package.json文件解析（author:慧敏）

一、必须属性

二、描述信息

4. contributors

5. homepage

6. repository

7. bugs

三、依赖配置

1. dependencies

2. devDependencies

3. peerDependencies

4. optionalDependencies

5. bundledDependencies

6. engines

四、脚本配置

1. scripts

2. config

五、文件&目录

1. main

2. browser

3. module

4. bin

5. files

6. man

7. directories

六、发布配置

1. private

2. preferGlobal

3. publishConfig

4. os

5. cpu

6. license

七、第三方配置

1. typings

2. eslintConfig

3. babel

4. unpkg

5. lint-staged

6. gitHooks

7. browserslist

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

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

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

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

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

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

公告