package.json 里面有許許多多的配置，與項(xiàng)目息息相關(guān)，了解它們有助于了解項(xiàng)目，提效開發(fā)，規(guī)范代碼。

今天主要介紹一些常見配置，我把它們分為了 7 大類：

1. 描述配置
2. 文件配置
3. 腳本配置
4. 依賴配置
5. 發(fā)布配置
6. 系統(tǒng)配置
7. 第三方配置

1. 描述配置

主要是項(xiàng)目的基本信息，包括名稱，版本，描述，倉庫，作者等，部分會(huì)展示在 npm 官網(wǎng)上。

name

項(xiàng)目的名稱，如果是第三方包的話，其他人可以通過該名稱使用 npm install 進(jìn)行安裝。

"name": "react"

version

項(xiàng)目的版本號(hào)，開源項(xiàng)目的版本號(hào)通常遵循 semver 語義化規(guī)范，具體規(guī)則如下圖所示：

簡單介紹一下：

• 1 代表主版本號(hào) Major，通常在涉及重大功能更新，產(chǎn)生了破壞性變更時(shí)會(huì)更新此版本號(hào)
• 2 代表次版本號(hào) Minor，在引入了新功能，但未產(chǎn)生破壞性變更，依然向下兼容時(shí)會(huì)更新此版本號(hào)
• 3 代表修訂號(hào) Patch，在修復(fù)了一些問題，也未產(chǎn)生破壞性變更時(shí)會(huì)更新此版本號(hào)

除了 X.Y.Z 這樣的標(biāo)準(zhǔn)版本號(hào)，還有 Pre-release 和 Metadata 來描述項(xiàng)目的測(cè)試版本，關(guān)于 semver 規(guī)范更多的內(nèi)容，可以參考https://juejin.cn/post/7122240572491825160 。

回到 package.json 的 version 字段，name + version 能共同構(gòu)成一個(gè)完全唯一的項(xiàng)目標(biāo)識(shí)符，所以它兩是最重要的兩個(gè)字段。

"version": "18.2.0"

repository

項(xiàng)目的倉庫地址以及版本控制信息。

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

description

項(xiàng)目的描述，會(huì)展示在 npm 官網(wǎng)，讓別人能快速了解該項(xiàng)目。

"description": "React is a JavaScript library for building user interfaces."

keywords

一組項(xiàng)目的技術(shù)關(guān)鍵詞，比如 Ant Design 組件庫的 keywords 如下：

"keywords": [
  "ant",
  "component",
  "components",
  "design",
  "framework",
  "frontend",
  "react",
  "react-component",
  "ui"
 ],

好的關(guān)鍵詞可以幫助別人在 npm 官網(wǎng)上更好地檢索到此項(xiàng)目，增加曝光率。

homepage

項(xiàng)目主頁的鏈接，通常是項(xiàng)目 github 鏈接，項(xiàng)目官網(wǎng)或文檔首頁。

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

bugs

項(xiàng)目 bug 反饋地址，通常是 github issue 頁面的鏈接。

"bugs": "https://github.com/vuejs/core/issues"

license

項(xiàng)目的開源許可證。項(xiàng)目的版權(quán)擁有人可以使用開源許可證來限制源碼的使用、復(fù)制、修改和再發(fā)布等行為。常見的開源許可證有 BSD、MIT、Apache 等，它們的區(qū)別可以參考：如何選擇開源許可證？https://www.ruanyifeng.com/blog/2011/05/how_to_choose_free_software_licenses.html

"license": "MIT"

author

項(xiàng)目作者。

"author": "Li jiaxun",

2. 文件配置

包括項(xiàng)目所包含的文件，以及入口等信息。

files

項(xiàng)目在進(jìn)行 npm 發(fā)布時(shí)，可以通過 files 指定需要跟隨一起發(fā)布的內(nèi)容來控制 npm 包的大小，避免安裝時(shí)間太長。

發(fā)布時(shí)默認(rèn)會(huì)包括 package.json，license，README 和main 字段里指定的文件。忽略 node_modules，lockfile 等文件。

在此基礎(chǔ)上，我們可以指定更多需要一起發(fā)布的內(nèi)容?？梢允菃为?dú)的文件，整個(gè)文件夾，或者使用通配符匹配到的文件。

"files": [
  "filename.js",
  "directory/",
  "glob/*.{js,json}"
 ]

一般情況下，files 里會(huì)指定構(gòu)建出來的產(chǎn)物以及類型文件，而 src，test 等目錄下的文件不需要跟隨發(fā)布。

type

在 node 支持 ES 模塊后，要求 ES 模塊采用 .mjs? 后綴文件名。只要遇到 .mjs 文件，就認(rèn)為它是 ES 模塊。如果不想修改文件后綴，就可以在 package.json文件中，指定 type 字段為 module。

"type": "module"

這樣所有 .js 后綴的文件，node 都會(huì)用 ES 模塊解釋。

$ node index.js

如果還要使用 CommonJS 模塊規(guī)范，那么需要將 CommonJS 腳本的后綴名都改成.cjs，不過兩種模塊規(guī)范最好不要混用，會(huì)產(chǎn)生異常報(bào)錯(cuò)。

main

項(xiàng)目發(fā)布時(shí)，默認(rèn)會(huì)包括 package.json，license，README 和main 字段里指定的文件，因?yàn)?main 字段里指定的是項(xiàng)目的入口文件，在 browser 和 Node 環(huán)境中都可以使用。

如果不設(shè)置 main? 字段，那么入口文件就是根目錄下的 index.js。

比如 packageA 的 main 字段指定為 index.js。

"main": "./index.js"

我們引入 packageA 時(shí)，實(shí)際上引入的就是 node_modules/packageA/index.js。

這是早期只有 CommonJS 模塊規(guī)范時(shí)，指定項(xiàng)目入口的唯一屬性。

browser

main 字段里指定的入口文件在 browser 和 Node 環(huán)境中都可以使用。如果只想在 web 端使用，不允許在 server 端使用，可以通過 browser 字段指定入口。

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

module

同樣，項(xiàng)目也可以指定 ES 模塊的入口文件，這就是 module 字段的作用。

"module": "./index.mjs"

當(dāng)一個(gè)項(xiàng)目同時(shí)定義了 main，browser 和 module，像 webpack，rollup 等構(gòu)建工具會(huì)感知這些字段，并會(huì)根據(jù)環(huán)境以及不同的模塊規(guī)范來進(jìn)行不同的入口文件查找。

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

比如 webpack 構(gòu)建項(xiàng)目時(shí)默認(rèn)的 target 為 'web'，也就是 Web 構(gòu)建。它的 resolve.mainFeilds 字段默認(rèn)為 ['browser', 'module', 'main']。

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

此時(shí)會(huì)按照 browser -> module -> main 的順序來查找入口文件。

exports

node 在 14.13 支持在 package.json 里定義 exports 字段，擁有了條件導(dǎo)出的功能。

exports 字段可以配置不同環(huán)境對(duì)應(yīng)的模塊入口文件，并且當(dāng)它存在時(shí)，它的優(yōu)先級(jí)最高。

比如使用 require? 和 import 字段根據(jù)模塊規(guī)范分別定義入口：

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

這樣的配置在使用 import 'xxx'? 和 require('xxx')? 時(shí)會(huì)從不同的入口引入文件，exports 也支持使用 browser? 和 node 字段定義 browser 和 Node 環(huán)境中的入口。

上方的寫法其實(shí)等同于：

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

為什么要加一個(gè)層級(jí)，把 require 和 import 放在 "." 下面呢？

因?yàn)?exports 除了支持配置包的默認(rèn)導(dǎo)出，還支持配置包的子路徑。

比如一些第三方 UI 包需要引入對(duì)應(yīng)的樣式文件才能正常使用。

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

我們可以使用 exports 來封裝文件路徑：

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

用戶引入時(shí)只需：

import `packageA/style`;

除了對(duì)導(dǎo)出的文件路徑進(jìn)行封裝，exports 還限制了使用者不可以訪問未在 "exports" 中定義的任何其他路徑。

比如發(fā)布的 dist 文件里有一些內(nèi)部模塊 dist/internal/module? ，被用戶單獨(dú)引入使用的話可能會(huì)導(dǎo)致主模塊不可用。為了限制外部的使用，我們可以不在 exports 定義這些模塊的路徑，這樣外部引入 packageA/dist/internal/module 模塊的話就會(huì)報(bào)錯(cuò)。

結(jié)合上面入口文件配置的知識(shí)，再來看看下方 vite 官網(wǎng)推薦的第三方庫入口文件的定義，就很容易理解了。

workspaces

項(xiàng)目的工作區(qū)配置，用于在本地的根目錄下管理多個(gè)子項(xiàng)目?？梢宰詣?dòng)地在 npm install 時(shí)將 workspaces 下面的包，軟鏈到根目錄的 node_modules 中，不用手動(dòng)執(zhí)行 npm link 操作。

workspaces 字段接收一個(gè)數(shù)組，數(shù)組里可以是文件夾名稱或者通配符。比如：

"workspaces": [
  "workspace-a"
]

表示在 workspace-a 目錄下還有一個(gè)項(xiàng)目，它也有自己的 package.json。

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

通常子項(xiàng)目都會(huì)平鋪管理在 packages 目錄下，所以根目錄下 workspaces 通常配置為：

"workspaces": [
  "packages/*"
]

3. 腳本配置

scripts

指定項(xiàng)目的一些內(nèi)置腳本命令，這些命令可以通過 npm run 來執(zhí)行。通常包含項(xiàng)目開發(fā)，構(gòu)建 等 CI 命令，比如：

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

我們可以使用命令 npm run build? / yarn build 來執(zhí)行項(xiàng)目構(gòu)建。

除了指定基礎(chǔ)命令，還可以配合 pre 和 post 完成命令的前置和后續(xù)操作，比如：

"scripts": {
  "build": "webpack",
  "prebuild": "xxx", // build 執(zhí)行之前的鉤子
  "postbuild": "xxx" // build 執(zhí)行之后的鉤子
}

當(dāng)執(zhí)行 npm run build 命令時(shí)，會(huì)按照 prebuild -> build -> postbuild 的順序依次執(zhí)行上方的命令。

但是這樣的隱式邏輯很可能會(huì)造成執(zhí)行工作流的混亂，所以 pnpm 和 yarn2 都已經(jīng)廢棄掉了這種 pre/post 自動(dòng)執(zhí)行的邏輯，參考 pnpm issue 討論 https://github.com/pnpm/pnpm/issues/2891

如果需要手動(dòng)開啟，pnpm 項(xiàng)目可以設(shè)置 .npmrc enable-pre-post-scripts=true。

enable-pre-post-scripts=true

config

config 用于設(shè)置 scripts 里的腳本在運(yùn)行時(shí)的參數(shù)。比如設(shè)置 port 為 3001：

"config": {
  "port": "3001"
}

在執(zhí)行腳本時(shí)，我們可以通過 npm_package_config_port 這個(gè)變量訪問到 3001。

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

4. 依賴配置

項(xiàng)目可能會(huì)依賴其他包，需要在 package.json 里配置這些依賴的信息。

dependencies

運(yùn)行依賴，也就是項(xiàng)目生產(chǎn)環(huán)境下需要用到的依賴。比如 react，vue，狀態(tài)管理庫以及組件庫等。

使用 npm install xxx? 或則 npm install xxx --save 時(shí)，會(huì)被自動(dòng)插入到該字段中。

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

devDependencies

開發(fā)依賴，項(xiàng)目開發(fā)環(huán)境需要用到而運(yùn)行時(shí)不需要的依賴，用于輔助開發(fā)，通常包括項(xiàng)目工程化工具比如 webpack，vite，eslint 等。

使用 npm install xxx -D? 或者 npm install xxx --save-dev 時(shí)，會(huì)被自動(dòng)插入到該字段中。

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

peerDependencies

同伴依賴，一種特殊的依賴，不會(huì)被自動(dòng)安裝，通常用于表示與另一個(gè)包的依賴與兼容性關(guān)系來警示使用者。

比如我們安裝 A，A 的正常使用依賴 B@2.x 版本，那么 B@2.x 就應(yīng)該被列在 A 的 peerDependencies 下，表示“如果你使用我，那么你也需要安裝 B，并且至少是 2.x 版本”。

比如 React 組件庫 Ant Design，它的 package.json 里 peerDependencies 為

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

表示如果你使用 Ant Design，那么你的項(xiàng)目也應(yīng)該安裝 react 和 react-dom，并且版本需要大于等于 16.9.0。

optionalDependencies

可選依賴，顧名思義，表示依賴是可選的，它不會(huì)阻塞主功能的使用，安裝或者引入失敗也無妨。這類依賴如果安裝失敗，那么 npm 的整個(gè)安裝過程也是成功的。

比如我們使用 colors 這個(gè)包來對(duì) console.log 打印的信息進(jìn)行著色來增強(qiáng)和區(qū)分提示，但它并不是必需的，所以可以將其加入到 optionalDependencies，并且在運(yùn)行時(shí)處理引入失敗的邏輯。

使用 npm install xxx -O? 或者 npm install xxx --save-optional 時(shí)，依賴會(huì)被自動(dòng)插入到該字段中。

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

peerDependenciesMeta

同伴依賴也可以使用 peerDependenciesMeta 將其指定為可選的。

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

bundleDependencies

打包依賴。它的值是一個(gè)數(shù)組，在發(fā)布包時(shí)，bundleDependencies 里面的依賴都會(huì)被一起打包。

比如指定 react 和 react-dom 為打包依賴：

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

在執(zhí)行 npm pack 打包生成 tgz 壓縮包中，將出現(xiàn) node_modules 并包含 react 和 react-dom。

需要注意的是，這個(gè)字段數(shù)組中的值必須是在 dependencies，devDependencies 兩個(gè)里面聲明過的依賴才行。

普通依賴通常從 npm registry 安裝，但當(dāng)你想用一個(gè)不在 npm registry 里的包，或者一個(gè)被修改過的第三方包時(shí)，打包依賴會(huì)比普通依賴更好用。

overrides

overrides 可以重寫項(xiàng)目依賴的依賴，及其依賴樹下某個(gè)依賴的版本號(hào)，進(jìn)行包的替換。

比如某個(gè)依賴 A，由于一些原因它依賴的包 foo@1.0.0 需要替換，我們可以使用 overrides 修改 foo 的版本號(hào)：

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

當(dāng)然這樣會(huì)更改整個(gè)依賴樹里的 foo，我們可以只對(duì) A 下的 foo 進(jìn)行版本號(hào)重寫：

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

overrides 支持任意深度的嵌套。

如果在 yarn 里也想復(fù)寫依賴版本號(hào)，需要使用 resolution 字段，而在 pnpm 里復(fù)寫版本號(hào)需要使用 pnpm.overrides 字段。

5. 發(fā)布配置

主要是和項(xiàng)目發(fā)布相關(guān)的配置。

private

如果是私有項(xiàng)目，不希望發(fā)布到公共 npm 倉庫上，可以將 private 設(shè)為 true。

"private": true

publishConfig

顧名思義，publishConfig 就是 npm 包發(fā)布時(shí)使用的配置。

比如在安裝依賴時(shí)指定了 registry 為 taobao 鏡像源，但發(fā)布時(shí)希望在公網(wǎng)發(fā)布，就可以指定 publishConfig.registry。

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

6. 系統(tǒng)配置

和項(xiàng)目關(guān)聯(lián)的系統(tǒng)配置，比如 node 版本或操作系統(tǒng)兼容性之類。這些要求只會(huì)起到提示警告的作用，即使用戶的環(huán)境不符合要求，也不影響安裝依賴包。

engines

一些項(xiàng)目由于兼容性問題會(huì)對(duì) node 或者包管理器有特定的版本號(hào)要求，比如：

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

要求 node 版本大于等于 14 且小于 16，同時(shí) pnpm 版本號(hào)需要大于 7。

os

在 linux 上能正常運(yùn)行的項(xiàng)目可能在 windows 上會(huì)出現(xiàn)異常，使用 os 字段可以指定項(xiàng)目對(duì)操作系統(tǒng)的兼容性要求。

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

cpu

指定項(xiàng)目只能在特定的 CPU 體系上運(yùn)行。

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

7. 第三方配置

一些第三方庫或應(yīng)用在進(jìn)行某些內(nèi)部處理時(shí)會(huì)依賴這些字段，使用它們時(shí)需要安裝對(duì)應(yīng)的第三方庫。

types 或者 typings

指定 TypeScript 的類型定義的入口文件

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

unpkg

可以讓 npm 上所有的文件都開啟 CDN 服務(wù)。

比如 vue package.json 的 unpkg 定義為 dist/vue.global.js

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

當(dāng)我們想通過 CDN 的方式使用鏈接引入 vue 時(shí)。

訪問 https://unpkg.com/vue? 會(huì)重定向到 https://unpkg.com/vue@3.2.37/dist/vue.global.js，其中 3.2.27 是 Vue 的最新版本。

jsdelivr

與 unpkg 類似，vue 通過如下的配置

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

訪問 https://cdn.jsdelivr.net/npm/vue 實(shí)際上獲取到的是 jsdelivr 字段里配置的文件地址。

browserslist

設(shè)置項(xiàng)目的瀏覽器兼容情況。babel 和 autoprefixer 等工具會(huì)使用該配置對(duì)代碼進(jìn)行轉(zhuǎn)換。當(dāng)然你也可以使用 .browserslistrc 單文件配置。

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

sideEffects

顯示設(shè)置某些模塊具有副作用，用于 webpack 的 tree-shaking 優(yōu)化。

比如在項(xiàng)目中整體引入 Ant Design 組件庫的 css 文件。

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

如果 Ant Design 的 package.json 里不設(shè)置 sideEffects，那么 webapck 構(gòu)建打包時(shí)會(huì)認(rèn)為這段代碼只是引入了但并沒有使用，可以 tree-shaking 剔除掉，最終導(dǎo)致產(chǎn)物缺少樣式。

所以 Ant Design 在 package.json 里設(shè)置了如下的 sideEffects，來告知 webpack，這些文件具有副作用，引入后不能被刪除。

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

lint-staged

lint-staged 是用于對(duì) git 的暫存區(qū)的文件進(jìn)行操作的工具，比如可以在代碼提交前執(zhí)行 lint 校驗(yàn)，類型檢查，圖片優(yōu)化等操作。

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

lint-staged 通常配合 husky 這樣的 git-hooks 工具一起使用。git-hooks 用來定義一個(gè)鉤子，這些鉤子方法會(huì)在 git 工作流程中比如 pre-commit，commit-msg 時(shí)觸發(fā)，可以把 lint-staged 放到這些鉤子方法中。

8. 結(jié)語

今天我們簡單了解了 package.json 的常見配置。有了這些知識(shí)，我敢說絕大多數(shù)項(xiàng)目的 package.json 你都能毫無壓力的閱讀。

但 package.json 里的內(nèi)容遠(yuǎn)不止如此，比如 semver 規(guī)范，入口文件，項(xiàng)目依賴等都還有很多值得深入的內(nèi)容，認(rèn)識(shí)他們只是第一步。

9. 參考

https://docs.npmjs.com/cli/v8/configuring-npm/package-json

https://zhuanlan.zhihu.com/p/548202395 by WangHaoyu

https://juejin.cn/post/7095903278084390948 by 摸魚的春哥

https://juejin.cn/post/7122240572491825160 by 摸魚的春哥

https://zhuanlan.zhihu.com/p/29855253 by 風(fēng)清洋

https://juejin.cn/post/7023539063424548872 by CUGGZ

https://segmentfault.com/a/1190000016365409 by senntyou

https://github.com/SunshowerC/blog/issues/8 by SunshowerC

https://www.ruanyifeng.com/blog/2020/08/how-nodejs-use-es6-module.html by 阮一峰