package.json配置指南

前言

package.json 是一個(gè)用于描述和配置項(xiàng)目的重要文件，其中包含了許多字段和選項(xiàng)，可以影響項(xiàng)目的構(gòu)建、依賴管理、腳本執(zhí)行等方面。了解這些字段可以幫助開(kāi)發(fā)者更好地理解和控制項(xiàng)目的行為。
package.json對(duì)于大部分前端開(kāi)發(fā)者來(lái)說(shuō)，知道dependencies與devDependencies就夠了。但對(duì)于庫(kù)開(kāi)發(fā)者或有更高級(jí)需求的開(kāi)發(fā)者來(lái)說(shuō)，了解 package.json 的其他字段是非常有必要的。
本文介紹的字段分為官方字段與非官方字段。非官方字段是被主流打包工具（webpack，Rollup）所支持， 旨在提供更高級(jí)的配置和功能，以滿足特定的構(gòu)建需求，可能不具備通用性。
目前版本：v7.24.2

一、必須屬性

1. name

定義項(xiàng)目的名稱，不能以'.'和'_'開(kāi)頭，不能包含大寫(xiě)字母

2. version

定義項(xiàng)目的版本號(hào)，格式為：大版本號(hào).次版本號(hào).修訂號(hào)

二、描述信息

1. description

項(xiàng)目描述

2. keywords

項(xiàng)目關(guān)鍵詞

3. author

項(xiàng)目作者

 'author': 'name (http://barnyrubble.tumblr.com/)'

4. contributors

項(xiàng)目貢獻(xiàn)者

'contributors': [
    'name <b@rubble.com> (http://barnyrubble.tumblr.com/)'
  ]

5. homepage

項(xiàng)目主頁(yè)地址

6. repository

項(xiàng)目代碼倉(cāng)庫(kù)地址

7. bugs

項(xiàng)目提交問(wèn)題的地址
//提交問(wèn)題的地址和反饋的郵箱,url通常是Github中的issues頁(yè)面

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

8. funding

指定項(xiàng)目的資金支持方式和鏈接

'funding': {
    'type': 'patreon',
    'url': 'https://www.patreon.com/my-module'
  }

三、依賴配置

1. dependencies

生產(chǎn)環(huán)境的依賴包
如果不使用脫字符（^），安裝的版本號(hào)固定；如果使用，則能安裝當(dāng)前大版本的最新版本，在package-lock.json中可查看當(dāng)前實(shí)際安裝的版本。

2. devDependencies

開(kāi)發(fā)環(huán)境的依賴包，例如webpack、vite、babel、ESLint等，不會(huì)被安裝到生產(chǎn)環(huán)境中

3. peerDependencies

對(duì)等依賴的作用：

減小打包體積：例如使用react開(kāi)發(fā)的組件庫(kù)，安裝react是必不可少的，而使用組件庫(kù)的開(kāi)發(fā)者，本地項(xiàng)目肯定安裝了react，因此開(kāi)發(fā)的組件庫(kù)中不必把react打包進(jìn)去（期望項(xiàng)目的使用者來(lái)提供這些模塊的實(shí)現(xiàn)）。

版本一致性：使用你的組件庫(kù)的開(kāi)發(fā)者需要確保他們項(xiàng)目中安裝了與你聲明的對(duì)等依賴版本兼容的包，以確保組件庫(kù)正常運(yùn)行。

示例：聲明要使用組件庫(kù)，需在項(xiàng)目中安裝大于17.0.1版本的react

'peerDependencies': {
    'react': '>17.0.1'
  }

4. peerDependenciesMeta

將對(duì)等依賴標(biāo)記為可選，如果用戶沒(méi)有安裝對(duì)等依賴，npm不會(huì)發(fā)出警告

'peerDependenciesMeta': {
    'react': {
      'optional': true //標(biāo)記為可選
    }
  }

5. bundledDependencies

聲明捆綁依賴項(xiàng)（使用情景較少）

6. optionalDependencies

聲明可選依賴項(xiàng)（使用情景較少）

7. engines

聲明對(duì)npm或node的版本要求

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

engines只是起一個(gè)說(shuō)明的作用，即使用戶安裝的版本不符合要求，也不影響依賴包的安裝。

8. workspaces

單個(gè)代碼庫(kù)中統(tǒng)一管理多個(gè)包（monorepo），在workspaces聲明目錄下的package會(huì)軟鏈到根目錄的node_modules中。

1. 初始化項(xiàng)目

npm init -y

2. 聲明本項(xiàng)目是workspaces模式

'private':'true',
  'workspaces': [
    'packages/*' 
  ],

表示所有子包都在packages文件夾下

3. 創(chuàng)建子包p1

npm init -w packages/p1 -y

在node_modules/.package-lock.json中可以看到 'link': true 鏈接符號(hào)信息

4. 新建packages/p1/index.js

module.exports = 'p1包';

5. 創(chuàng)建子包p2

npm init -w packages/p2 -y

6. 將子包p1添加到p2中

npm i p1 -w p2

安裝，卸載等命令都是一樣的，只是多了'--workspace='參數(shù)（簡(jiǎn)寫(xiě)-w），???來(lái)指定在哪個(gè)包中執(zhí)行命令

7. 子包p2使用p1

const p1 = require('p1');

console.log('使用', p1);

module.exports = 'p2包';

workspaces功能與lerna類似，如果只需簡(jiǎn)單地管理多個(gè)包，workspaces足夠了。lerna具有版本管理，發(fā)包提示，簡(jiǎn)化多包項(xiàng)目發(fā)布流程等更多功能。

四、腳本配置

1. scripts

腳本入口

2. config

用于定義項(xiàng)目的配置項(xiàng)，例如設(shè)置環(huán)境變量

1. config 配置

'config': {
    'baseUrl': 'https://example.com'
  }

2. scripts 配置

'scripts': {
    'start': 'node index.js',
  },

3. 新建index.js

//使用process.env.npm_package_config_XXX取值
console.log(process.env.npm_package_config_baseUrl)

運(yùn)行 npm run start，終端打印出 example.com

五、文件&目錄

1. module（非官方字段）

指定 ES 模塊入口文件
示例：當(dāng)其他開(kāi)發(fā)者在他們的項(xiàng)目中導(dǎo)入你的包時(shí)，會(huì)加載并執(zhí)行包中的dist/index.esm.js

'main': 'dist/index.esm.js'

2. main

指定 CommonJS 模塊或 ES 模塊入口文件。如果不指定該字段，默認(rèn)是根目錄下的index.js
提示：從 Node.js 12.20.0 版本開(kāi)始，'main' 字段也可以指定 ES 模塊的入口文件

3. browser

指定瀏覽器使用的入口文件，例如umd模塊。

4. types（非官方字段）

指定 TypeScript 類型聲明文件（.d.ts 文件）的路徑

5. exports（非官方字段）

當(dāng)打包工具支持exports字段時(shí)（webpack、Rollup 等），以上main，browser，module，types四個(gè)字段都被忽略

'.' 表示默認(rèn)導(dǎo)出
'import': 指定了 ES module (ESM) 規(guī)范下的導(dǎo)出文件路徑
'require': 指定了 CommonJS 規(guī)范下的導(dǎo)出文件路徑
'browser': 指定了用于瀏覽器環(huán)境的導(dǎo)出文件路徑
'types': 指定了類型聲明文件的路徑

'exports': {
    '.': {
      'import': './dist/index.esm.js',
      'require': './dist/index.cjs.js',
      'browser': './dist/index.umd.js',
      'types': './dist/index.d.ts'
    }
  }

導(dǎo)出其他文件，例如除了導(dǎo)出默認(rèn)路徑，導(dǎo)出源文件

'exports':{
    ...
  './main' : './src/main.js'
},

其他項(xiàng)目中使用

import main from 'packageName'; // . 方式定義的
import main from 'packageName/main'; // ./main 方式定義的

6. type（非官方字段）

指定模塊系統(tǒng)的使用方式，'commonjs'，'module'，'umd'，'json'
示例：指定模塊系統(tǒng)為ES module模式，使用CommonJS文件時(shí)，需顯式的定義為 .cjs 文件擴(kuò)展名，來(lái)明確指定這些文件為 CommonJS 模塊

  'type':'module'

7. files

指定哪些包被推送到npm服務(wù)器中
示例：只推送index.js和dist包到npm服務(wù)器

'files': [
    'index.js',
    'dist'
  ],

可以在項(xiàng)目根目錄新建一個(gè).npmignore文件，說(shuō)明不需要提交到npm服務(wù)器的文件，類似.gitignore。寫(xiě)在這個(gè)文件中的文件即便被寫(xiě)在files屬性里也會(huì)被排除在外

8. bin

定義在全局安裝時(shí)可執(zhí)行的命令（使用情景較少）

9. man

Linux 中的幫助指令（使用情景較少）

10. directories

定義項(xiàng)目目錄結(jié)構(gòu)的字段（使用情景較少）

六、發(fā)布配置

1. private

防止私有包發(fā)布到npm服務(wù)器，要發(fā)布到npm上設(shè)為false

2. preferGlobal（非官方字段）

當(dāng)設(shè)置 'preferGlobal' 字段為 true 時(shí)，它表示你的包更適合以全局方式安裝，而不是作為項(xiàng)目的依賴項(xiàng)進(jìn)行本地安裝。

這個(gè)字段的設(shè)置是為了向用戶傳達(dá)關(guān)于你的包的最佳使用方式的建議。它并不會(huì)直接影響包的安裝方式或包管理器的行為。

3. publishConfig

在發(fā)布包時(shí)指定特定的配置
示例：指定包發(fā)布的注冊(cè)表 URL，指定所有用戶都可以訪問(wèn)（私有的會(huì)收費(fèi)）

'publishConfig': {
    'registry': 'https://registry.npmjs.org/',
    'access': 'public'
  }

4. os

指定你的包適用的操作系統(tǒng)
示例：包只適用于darwin（macOS）和 linux

'os': ['darwin', 'linux']

示例：禁用win32
'os' ['!win32'] //禁用的操作系統(tǒng)

5. cpu

該配置和OS配置類似，用CPU可以更準(zhǔn)確的限制用戶的安裝環(huán)境

6. license

指定軟件的開(kāi)源協(xié)議：
ISC：在所有副本中保留版權(quán)聲明和許可證聲明，使用者就可以拿你的代碼做任何想做的事情，你也無(wú)需承擔(dān)任何責(zé)任
MIT：在所有副本或主要部分中保留版權(quán)聲明和許可證聲明，使用者就可以拿你的代碼做任何想做的事情，你也無(wú)需承擔(dān)任何責(zé)任
開(kāi)源協(xié)議查詢地址：opensource.org/licenses/

七、第三方配置（非官方字段）

1. eslintConfig

eslint的配置，更推薦新建 .eslintrc 進(jìn)行配置
使用參考：新建 .eslintrc

2. babel

babel的配置，更推薦新建 .babelrc 進(jìn)行配置

3. unpkg

unpkg 是一個(gè)基于 CDN 的前端包托管服務(wù)，用于在瀏覽器中直接引用和加載 npm 上發(fā)布的包。
無(wú)需下載，直接通過(guò) <script> 標(biāo)簽引用

<script src='https://unpkg.com/package-name@version'></script>

4. lint-staged

lint-staged是一個(gè)在Git暫存文件上運(yùn)行l(wèi)inters的工具，通常配合gitHooks一起使用。
使用參考：配置 husky、lint-staged、@commitlint/cli

5. browserslist

告知支持哪些瀏覽器及版本，Autoprefixer常用到它

'browserslist': [
    'defaults',
    'not ie < 8',
    'last 2 versions',
    '> 1%',
    'iOS 7',
    'last 3 iOS versions'
  ]

6. sideEffects

指示包是否具有副作用，協(xié)助Webpack，Rollup等進(jìn)行tree shaking
多數(shù)情況下可以直接設(shè)置為false，這樣打包工具就會(huì)自動(dòng)刪除未被import的代碼
但是有些情況例外

有一些特定的模塊文件，它們執(zhí)行一些副作用操作，如注冊(cè)全局事件監(jiān)聽(tīng)器、修改全局狀態(tài)等。

告訴構(gòu)建工具不要將樣式文件排除在無(wú)用代碼消除的優(yōu)化范圍之外

'sideEffects': ['./path/to/module.js', '*.css']

七、其他用法

模塊引用其他模塊

"node-sass": "npm:dart-sass@^1.25.0",

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書(shū)系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

  • package.json 非官方字段集合 package.json 官方字段請(qǐng)參考 https://docs.np...
    senntyou閱讀 783評(píng)論 0贊 1
  • 概述 每個(gè)項(xiàng)目的根目錄下面，一般都有一個(gè)package.json文件，定義了這個(gè)項(xiàng)目所需要的各種模塊，以及項(xiàng)目的配...
    Mr無(wú)愧于心閱讀 4,407評(píng)論 0贊 1
  • 如果使用 JavaScript、或者曾經(jīng)與 JavaScript 項(xiàng)目、Node.js 或前端項(xiàng)目進(jìn)行過(guò)交互，則肯...
    筆墨是小舟閱讀 510評(píng)論 0贊 1
  • 每個(gè)項(xiàng)目的根目錄下面，一般都有一個(gè)package.json文件，定義了這個(gè)項(xiàng)目所需要的各種模塊，以及項(xiàng)目的配置信息...
    OnlyCozj閱讀 4,351評(píng)論 0贊 2
  • 概述 package.json文件，定義了這個(gè)項(xiàng)目所需要的各種模塊，以及項(xiàng)目的配置信息（比如名稱、版本、許可證等元...
    chasing_dream閱讀 540評(píng)論 0贊 0

友情鏈接更多精彩內(nèi)容