package.json配置

1. 描述配置

1.1 Name 项目的名称

名称的长度 <= 214 个字符，不能以 “.” 和“_”开头，不能包含大写字母（这是因为当软件包在 npm 上发布时，会基于此属性获得自己的 URL，所以不能包含非 URL 安全字符（non-url-safe））；
名称可以作为参数被传入 require(“”)，用来导入模块，所以应当尽可能的简短、语义化；
名称不能和其他模块的名称重复，可以使用 npm view 命令查询模块名是否重复，如果不重复就会提示 404。

1.2 version 项目包的版本号

版本号的命名遵循语义化版本 2.0.0 规范，格式为：「主版本号. 次版本号. 修订号」，通常情况下，修改主版本号是做了大的功能性的改动，修改次版本号是新增了新功能，修改修订号就是修复了一些 bug
如果某个版本的改动较大，并且不稳定，可能无法满足预期的兼容性需求，就需要发布先行版本，先行版本通过会加在版本号的后面，通过 “-” 号连接以点分隔的标识符和版本编译信息：内部版本（alpha）、公测版本（beta）和候选版本（rc，即 release candiate）

1.3 repository 项目代码的存放仓库地址及版本控制信息

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

1.4 description 项目包描述

会展示在 npm 官网，让别人能快速了解该项目

1.5 keywords 项目包关键字

一个字符串数组，用来增加项目包的曝光率

"keywords": [ "arco", "vue" ]

1.6 homepage 项目的主页地址

通常是项目 github 链接，项目官网或文档首页。

"homepage": "https://reactjs.org/"

1.7 bugs 项目问题提交地址

通常是 github issue 页面的链接

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

1.8 license 指定软件的开源协议

开源协议表述了其他人获得代码后拥有的权利，可以对代码进行何种操作，何种操作又是被禁止的。常见的协议如下：
MIT ：只要用户在项目副本中包含了版权声明和许可声明，他们就可以拿你的代码做任何想做的事情，你也无需承担任何责任。
Apache ：类似于 MIT ，同时还包含了贡献者向用户提供专利授权相关的条款。
GPL ：修改项目代码的用户再次分发源码或二进制代码时，必须公布他的相关修改。

1.9 author 项目包的作者

"author": "YX<xxxxx@xx.com> (https://yx.cn/user/123456)"
// 或者
"author": {
  "name": "YX",
  "email": "xxxxx@xx.com",
  "url": "https://yx.cn/user/123456"
}

1.10 contributors 项目包的贡献者

"contributors": [
     "YX1<xxxxx@xx.com> (https://juejin.cn/user/123456)",
     "YX2<xxxxx@xx.com> (https://juejin.cn/user/123456)"
 ]
 // 或者
"contributors": [
    {
       "name" : "YX1",
       "email" : "xxxxx@xx.com",
       "url" : "https://juejin.cn/user/123456"
   }, {
      "name" : "YX2",
      "email" : "xxxxx@xx.com",
      "url" : "https://juejin.cn/user/123456"
   }
 ]

2 文件配置

2.1 files 发布文件配置

当 npm 包发布时，files 指定的文件会被推送到 npm 服务器中，如果指定的是文件夹，那么该文件夹下面所有的文件都会被提交。

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

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

2.2 type

在 node 支持 ES 模块后，要求 ES 模块采用 .mjs 后缀文件名。只要遇到 .mjs 文件，就认为它是 ES 模块。如果不想修改文件后缀，就可以在 package.json文件中，指定 type 字段为 module。

"type": "module"

这样所有 .js 后缀的文件，node 都会用 ES 模块解释。

# 使用 ES 模块规范
$ node index.js

如果还要使用 CommonJS 模块规范，那么需要将 CommonJS 脚本的后缀名都改成.cjs，不过两种模块规范最好不要混用，会产生异常报错。

2.3 main 程序入口

项目发布时，默认会包括 package.json，license，README 和main 字段里指定的文件，因为 main 字段里指定的是项目的入口文件，在 browser 和 Node 环境中都可以使用。
如果不设置 main 字段，那么入口文件就是根目录下的 index.js。
比如 packageA 的 main 字段指定为 index.js。

"main": "./index.js"

我们引入 packageA 时，实际上引入的就是 node_modules/packageA/index.js。
这是早期只有 CommonJS 模块规范时，指定项目入口的唯一属性。

2.4 browser browser 环境下程序入口

main 字段里指定的入口文件在 browser 和 Node 环境中都可以使用。如果只想在 web 端使用，不允许在 server 端使用，可以通过 browser 字段指定入口。

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

2.5 module ESM 规范的程序入口

项目也可以指定 ES 模块的入口文件，这就是 module 字段的作用。browser 环境和 node 环境均可使用

"module": "./index.mjs"

当一个项目同时定义了 main，browser 和 module，像 webpack，rollup 等构建工具会感知这些字段，并会根据环境以及不同的模块规范来进行不同的入口文件查找。

"main": "./index.js", 
"browser": "./browser/index.js",
"module": "./index.mjs"

比如 webpack 构建项目时默认的 target 为 ‘web’，也就是 Web 构建。它的 resolve.mainFeilds 字段默认为 [‘browser’, ‘module’, ‘main’]。

module.exports = {
  //...
  resolve: {
    mainFields: ['browser', 'module', 'main'],
  },
};

此时会按照 browser -> module -> main 的顺序来查找入口文件。

2.6 exports 条件导出的功能

node 在 14.13 支持在 package.json 里定义 exports 字段，拥有了条件导出的功能。
exports 字段可以配置不同环境对应的模块入口文件，并且当它存在时，它的优先级最高。
比如使用 require 和 import 字段根据模块规范分别定义入口：

"exports": {
  ".": {
    "require": "./index.js",
    "import": "./index.mjs"
  }
 }
}

这样的配置在使用 import ‘xxx’ 和 require(‘xxx’) 时会从不同的入口引入文件，exports 也支持使用 browser 和 node 字段定义 browser 和 Node 环境中的入口。
上方的写法其实等同于：

"exports": {
  ".": {
    "require": "./index.js",
    "import": "./index.mjs"
  }
}

为什么要加一个层级，把 require 和 import 放在 “.” 下面呢？
因为 exports 除了支持配置包的默认导出，还支持配置包的子路径。
比如一些第三方 UI 包需要引入对应的样式文件才能正常使用。

import 'packageA/dist/css/index.css';

我们可以使用 exports 来封装文件路径：

"exports": {
  "./style": "./dist/css/index.css'
}

用户引入时只需：

import 'packageA/style';

除了对导出的文件路径进行封装，exports 还限制了使用者不可以访问未在 “exports” 中定义的任何其他路径。
比如发布的 dist 文件里有一些内部模块 dist/internal/module ，被用户单独引入使用的话可能会导致主模块不可用。为了限制外部的使用，我们可以不在 exports 定义这些模块的路径，这样外部引入 packageA/dist/internal/module 模块的话就会报错。
结合上面入口文件配置的知识，再来看看下方 vite 官网推荐的第三方库入口文件的定义，就很容易理解了。

2.7 workspaces 项目的工作区配置

用于在本地的根目录下管理多个子项目。可以自动地在 npm install 时将 workspaces 下面的包，软链到根目录的 node_modules 中，不用手动执行 npm link 操作。
workspaces 字段接收一个数组，数组里可以是文件夹名称或者通配符。比如：

"workspaces": [
  "workspace-a"
]

表示在 workspace-a 目录下还有一个项目，它也有自己的 package.json。

package.json
workspace-a
  └── package.json

通常子项目都会平铺管理在 packages 目录下，所以根目录下 workspaces 通常配置为：

"workspaces": [
  "packages/*"
]

2.8 bin 命令行工具入口

指定各个内部命令对应的可执行文件的位置

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

2.9 man Linux 中的帮助指令

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

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

2.10 directories 规范项目的目录

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

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

在实际的项目目录中，我们可能没有按照这个规范进行命名，那么就可以在 directories 字段指定每个目录对应的文件路径：

"directories": {
    "bin": "./bin",
    "lib": "./lib",
    "doc": "./doc",
    "test" "./test",
    "man": "./man"
}

3 脚本配置

3.1 scripts 指定项目的一些内置脚本命令，这些命令可以通过 npm run 来执行

通常包含项目开发，构建 等 CI 命令，比如：

"scripts": {
  "build": "webpack"
}

我们可以使用命令 npm run build / yarn build 来执行项目构建。
除了指定基础命令，还可以配合 pre 和 post 完成命令的前置和后续操作，比如：

"scripts": {
  "build": "webpack",
  "prebuild": "xxx", // build 执行之前的钩子
  "postbuild": "xxx" // build 执行之后的钩子
}

当执行 npm run build 命令时，会按照 prebuild -> build -> postbuild 的顺序依次执行上方的命令。
但是这样的隐式逻辑很可能会造成执行工作流的混乱，所以 pnpm 和 yarn2 都已经废弃掉了这种 pre/post 自动执行的逻辑

3.2 config 配置 scripts 运行时的配置参数

"config": {
  "port": 3000
}

在执行脚本时，我们可以通过 npm_package_config_port 这个变量访问到 3001。

console.log(process.env.npm_package_config_port); // 3001

4 依赖配置

4.1 dependencies 生产环境中所必须的依赖包

项目生产环境下需要用到的依赖。比如 react，vue，状态管理库以及组件库等
使用 npm install xxx 或则 npm install xxx --save 时，会被自动插入到该字段中。

"dependencies": {"react": "^18.2.0","react-dom": "^18.2.0"}

4.2 devDependencies 开发阶段需要的依赖包

开发依赖，项目开发环境需要用到而运行时不需要的依赖，用于辅助开发，通常包括项目工程化工具比如 webpack，vite，eslint 等。
使用 npm install xxx -D 或者 npm install xxx --save-dev 时，会被自动插入到该字段中。

"devDependencies": {"webpack": "^5.69.0"}

4.3 peerDependencies 兼容依赖

一种特殊的依赖，不会被自动安装，通常用于表示与另一个包的依赖与兼容性关系来警示使用者。
比如我们安装 A，A 的正常使用依赖 B@2.x 版本，那么 B@2.x 就应该被列在 A 的 peerDependencies 下，表示“如果你使用我，那么你也需要安装 B，并且至少是 2.x 版本”。
比如 React 组件库 Ant Design，它的 package.json 里 peerDependencies 为

"peerDependencies": {
  "react": ">=16.9.0",
  "react-dom": ">=16.9.0"
}

表示如果你使用 Ant Design，那么你的项目也应该安装 react 和 react-dom，并且版本需要大于等于 16.9.0。

4.4 optionalDependencies 不阻断安装依赖

表示依赖是可选的，它不会阻塞主功能的使用，安装或者引入失败也无妨。这类依赖如果安装失败，那么 npm 的整个安装过程也是成功的。
比如我们使用 colors 这个包来对 console.log 打印的信息进行着色来增强和区分提示，但它并不是必需的，所以可以将其加入到 optionalDependencies，并且在运行时处理引入失败的逻辑。
使用 npm install xxx -O 或者 npm install xxx --save-optional 时，依赖会被自动插入到该字段中。

"optionalDependencies": {
  "colors": "^1.4.0"
}

4.5 peerDependenciesMeta

兼容依赖也可以使用 peerDependenciesMeta 将其指定为可选的。

"peerDependencies": {
  "colors": "^1.4.0"
},
"peerDependenciesMeta": {
  "colors": {
    "optional": true
   }
 }

4.6 bundleDependencies 打包依赖

它的值是一个数组，在发布包时，bundleDependencies 里面的依赖都会被一起打包。
比如指定 react 和 react-dom 为打包依赖：

"bundleDependencies": [
  "react",
  "react-dom"
]

在执行 npm pack 打包生成 tgz 压缩包中，将出现 node_modules 并包含 react 和 react-dom。

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

普通依赖通常从 npm registry 安装，但当你想用一个不在 npm registry 里的包，或者一个被修改过的第三方包时，打包依赖会比普通依赖更好用。

4.7 overrides

overrides 可以重写项目依赖的依赖，及其依赖树下某个依赖的版本号，进行包的替换。
比如某个依赖 A，由于一些原因它依赖的包 foo@1.0.0 需要替换，我们可以使用 overrides 修改 foo 的版本号：

"overrides": {
  "foo": "1.1.0-patch"
}

当然这样会更改整个依赖树里的 foo，我们可以只对 A 下的 foo 进行版本号重写：

"overrides": {
  "A": {
    "foo": "1.1.0-patch",
  }
}

overrides 支持任意深度的嵌套。

如果在 yarn 里也想复写依赖版本号，需要使用 resolution 字段，而在 pnpm 里复写版本号需要使用
pnpm.overrides 字段。

5 发布配置

5.1 private 限制发布

如果是私有项目，不希望发布到公共 npm 仓库上，可以将 private 设为 true。

5.2 publishConfig npm 包发布时使用的配置

比如在安装依赖时指定了 registry 为 taobao 镜像源，但发布时希望在公网发布，就可以指定 publishConfig.registry。

"publishConfig": {
  "registry": "https://registry.npmjs.org/"
}

6 系统配置

6.1 engines 对npm和node的版本要求

一些项目由于兼容性问题会对 node 或者包管理器有特定的版本号要求，比如：

"engines": {
  "node": ">=14 <16",
  "pnpm": ">7"
}

要求 node 版本大于等于 14 且小于 16，同时 pnpm 版本号需要大于 7。

6.2 os 指定项目对操作系统的兼容性要求

在 linux 上能正常运行的项目可能在 windows 上会出现异常，使用 os 字段可以指定项目对操作系统的兼容性要求。

"os": ["darwin", "linux"]

6.3 cpu 指定项目只能在特定的 CPU 体系上运行

"cpu": ["x64", "ia32"]

7 第三方配置

7.1 types/typings 指定 TypeScript 的类型定义的入口文件

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

7.2 unpkg 开启 CDN 服务

可以让 npm 上所有的文件都开启 CDN 服务。
比如 vue package.json 的 unpkg 定义为 dist/vue.global.js

"unpkg": "dist/vue.global.js"

当我们想通过 CDN 的方式使用链接引入 vue 时。
访问 https://unpkg.com/vue 会重定向到 https://unpkg.com/vue@3.2.37/dist/vue.global.js，其中 3.2.27 是 Vue 的最新版本。

7.3 jsdelivr

与 unpkg 类似，vue 通过如下的配置

"jsdelivr": "dist/vue.global.js"

访问 https://cdn.jsdelivr.net/npm/vue 实际上获取到的是 jsdelivr 字段里配置的文件地址。

7.4 browserslist 设置项目的浏览器兼容情况

babel 和 autoprefixer 等工具会使用该配置对代码进行转换。当然你也可以使用 .browserslistrc 单文件配置。

"browserslist": ["> 1%","last 2 versions"]

7.5 sideEffects 显示设置某些模块具有副作用，用于 webpack 的 tree-shaking 优化

比如在项目中整体引入 Ant Design 组件库的 css 文件。

import 'antd/dist/antd.css'; // or 'antd/dist/antd.less'

如果 Ant Design 的 package.json 里不设置 sideEffects，那么 webapck 构建打包时会认为这段代码只是引入了但并没有使用，可以 tree-shaking 剔除掉，最终导致产物缺少样式。
所以 Ant Design 在 package.json 里设置了如下的 sideEffects，来告知 webpack，这些文件具有副作用，引入后不能被删除。

"sideEffects": [
  "dist/*",
  "es/**/style/*",
  "lib/**/style/*",
  "*.less"
]

7.6 lint-staged 一个在 Git 暂存文件上运行 linters 的工具

int-staged 是用于对 git 的暂存区的文件进行操作的工具，比如可以在代码提交前执行 lint 校验，类型检查，图片优化等操作。

"lint-staged": {
  "src/**/*.{js,jsx,ts,tsx}": [
    "eslint --fix",
    "git add -A"
  ]
}

lint-staged 通常配合 husky 这样的 git-hooks 工具一起使用。git-hooks 用来定义一个钩子，这些钩子方法会在 git 工作流程中比如 pre-commit，commit-msg 时触发，可以把 lint-staged 放到这些钩子方法中。