博客 / 詳情

返回

package.json 部分屬性解讀

name

定義項目（包）名。規則如下：

  • 不得多於 214 個字符（包含@<scope>/前綴在內）
  • 不得以.、_開頭，且不得包含大寫字母
  • 只允許使用 URL-safe 字符

version

定義項目（包）的當前版本號

description

定義項目（包）的簡要描述。registry 將提取該信息以方便搜索

keywords

定義項目（包）的關鍵字描述。registry 將提取該信息以方便檢索

license

<!-- TODO -->

homepage

項目（包）的主頁/文檔地址

bugs

項目（包）的問題彙報頁面地址或相關 email

repository

項目（包）所在的版本管理倉庫地址

author

項目（包）的作者信息。形如：

{
    "author"：{
        "name":"<name>",
        "email":"<email>",
        "url":"<homepage-url>",
    }
}

contributors

項目（包）的貢獻者信息。一般為數組形式，元素格式同 author

files

指定作為包發佈（publish）至 registry 時上傳的文件，可包含目錄和通配符。形如：

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

要點：

  • 通常包含構建產物及相關類型文件，而 src、test 等目錄下文件無需一同發佈
  • package.json、license、README 以及package.json#main指定的文件將被默認包含
  • node_modules、lockfile 等文件將被默認忽略
  • .npmignore 中所列文件即便位於 files 中也會被排除，其格式與.gitignore 類似。且若項目中缺少.npmignore，則默認將使用.gitignore 的內容

type

指定 Node.js 以何種模塊化形式解析.js後綴文件。可選值：

  • "commonjs"：默認值，視為 CommonJS
  • "module"：視為 ESM

注：不論該字段為何值，.cjs後綴文件始終視為 CommonJS，.mjs後綴文件始終視為 ESM

main

指定包作為 CommonJS 被引入時的入口文件路徑（默認為包目錄下的./index.js ）

module

指定包作為 ESM 被引入時的入口文件路徑。該屬性僅被現代化構建工具感知，node.js 的包引入機制會將其忽略，後者僅參考 main 和 exports

browser

指定包被用於構建瀏覽器端產物時的入口文件地址。該屬性僅被構建工具感知，且其指向文件通常為 IIEF 或 UMD 形式

exports

按最高優先級定義包的公共入口。具體如下：

  • 允許定義多個入口。形如：

    {
    "exports": {
        /* 對應包名引入 */
        ".": "./lib/index.js",
        /* 對應包子路徑引入，如 import <pkg> from '<pkg-name>/lib' */
        "./lib": "./lib/index.js",
        /**
         * 支持路徑通配符 *，後者可被展開為任意子路徑而不僅限於文件名
         * 此處設定 .js 後綴則限定了只導出 js 文件
         */
        "./feature/*.js": "./feature/*.js",
        /* 通過此方式限制某個子路徑下的包導出 */
        "./feature/private-internal/*": null,
        /* 一些 UI 包可能需要引入部分樣式才能正常使用 */
        "./style": "./dist/css/index.css",
        "./package.json": "./package.json"
    }
}

  • 提供不同環境下的情景導出，當作為 Node.js 包被引用時：

    {
    "exports": {
        /* 按 ESM 引入時的包入口 */
        "import": "./index-module.js",
        /* 按 CommonJS 引入時的包入口 */
        "require": "./index-require.js"
    }
}

    現代化構建工具如何處理則可參見：

    • vite#resolve.conditions
    • webpack#Package exports

注意：

  • 對於 Node.js v14 以及大多數現代化構建工具而言，其優先級高於 main
  • 未在 exports 中被顯式定義的入口（含 package.json）將無法被引入

  • 若 exports 中僅包含.屬性，則可將其簡寫。例如：

    {
    "exports": {
        ".": "./index.js"
    }
    /**
     * 可被簡寫為:
     *
     * "exports":"./index.js"
     */
}
  • 直接引入 node_modules 目錄下對應的包文件依然是可行的，如require(<path-to-node_modules>/<pkg>/<file>.js)

workspaces

指定項目的 workspaces 目錄，具體參見，接受通配符。形如：

{
    "workspaces": ["packages/*"]
}

directories

提供項目（包）元信息，常用子字段如下：

  • lib：有關庫在包中的確切位置
  • bin：所有可執行文件所在的目錄，可用於代替具有 bin 屬性
  • man：所有手冊頁所在的目錄
  • doc：有關包文檔所在目錄
  • example：有關示例代碼的目錄
  • test：有關測試文件所在目錄

bin

用於在帶有 CLI 的項目（包）中指定相關命令對應的可執行文件。形如：

{
    "bin": {
        "webpack": "bin/index.js"
    }
}

當其通過包管理工具被安裝時：

  • 全局安裝會在/usr/local/bin（win 默認C:\Users\<username>\AppData\Roaming\npm）目錄下創建指向對應可執行文件的軟鏈接

  • 局部安裝則將軟鏈接創建在項目的node_modules/.bin目錄下。對應命令可通過以下方式調用：

    • npx <command>
    • 或出現在package.json#scripts.<action>對應的腳本中

scripts

指定項目級腳本命令，後者可通過npm run <action>執行。形如：

{
    "scripts": {
        "<action>": "<command>",
        "pre<action>": "<pre-command>",
        "post<action>": "<post-command>"
    }
}

每個 action 還可通過添加pre/post前綴定義相應的前置/後續腳本命令，如當執行npm run build時會按 prebuild -> build -> postbuild 順序依次執行相應腳本

注意此類隱式邏輯很可能造成工作流混亂，因而在 pnpm 和 yarn2 中都已廢棄，參見。如需手動開啓：

  • pnpm 中可設置 .npmrc > enable-pre-post-scripts=true

config

為 scripts 腳本設置環境變量。形如：

{
    "config": {
        "<name>": "<value>"
    }
}

腳本執行時可以$npm_package_config_<name>形式訪問

dependencies

運行依賴，在生產環境下也會用到

devDependencies

開發依賴，在生產環境下不會用到。install 命令在以下情況下不會安裝 devDependencies：

  • 環境變量NODE_ENV為production時
  • 執行 install 命令時附帶選項--production=true

peerDependencies

同伴依賴，一種特殊的依賴，不會被自動安裝，常用於表示與另一個包的依賴與兼容性關係以警示使用者

比如安裝 A，A 的正常使用依賴 B@2.x 版本，則 B@2.x 應被列在 A 的 peerDependencies 下。例如 React 組件庫 Ant Design，其 peerDependencies 為

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

表示若使用 Ant Design，則項目也應安裝 react 和 react-dom，且版本需大於等於 16.9.0

optionalDependencies

可選依賴，表示依賴不會阻塞主功能的使用，安裝或者引入失敗也無妨。即使其安裝失敗，npm 的整個安裝過程也是成功的。使用 npm install xxx -O 或 npm install xxx --save-optional 時自動插入其中

如使用 colors 包來對 console.log 打印信息進行着色來增強和區分提示。它並非必需，所以可以將其列入 optionalDependencies，並在運行時處理引入失敗的邏輯

peerDependenciesMeta

同伴依賴也可以用 peerDependenciesMeta 將其指定為可選。例如：

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

bundleDependencies

打包依賴。其值為數組，在發佈包時 bundleDependencies 裏面的依賴都會被一併打包

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

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

則執行 npm pack 打包生成的 tgz 包中，將出現 node_modules 幷包含 react 和 react-dom

:::warning 注意
該字段數組中的值必須為 dependencies 或 devDependencies 內聲明過的依賴
:::

普通依賴通常從 npm registry 安裝，但若想用一個不在 npm registry 裏的包或一個被修改過的第三方包，打包依賴會比普通依賴更好用

overrides

overrides 可以重寫項目依賴的依賴、及其依賴樹下某個依賴的版本號，進行包的替換

例如某依賴 A，出於一些原因其依賴包 foo@1.0.0 需要替換，則可使用 overrides 修改 foo 的版本號：

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

當然這樣會更改整個依賴樹裏的 foo，可以只對 A 下的 foo 進行版本號重寫（overrides 支持任意深度的嵌套）：

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

若要在 yarn 中複寫依賴版本號，需使用 resolution 字段；而 pnpm 中則需用 pnpm.overrides 字段

private

若是私有項目，不希望發佈至公共 npm 倉庫上，可將 private 設為 true

publishConfig

顧名思義，即 npm 包發佈時使用的配置

例如在安裝依賴時指定了 registry 為 taobao 鏡像源，但發佈時希望在公網發佈，則可指定 publishConfig.registry：

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

<!-- 與項目關聯的系統配置，如 node 版本或操作系統兼容性之類。大多隻起到提示，即使用户環境不合要求也不影響依賴安裝 -->

engines

一些項目由於兼容性問題會對 node 或包管理器有特定版本號要求。如：

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

除非設置 engine-strict 標記，否則只充當建議

os

linux 正常運行的項目可能在 windows 上會出現異常，使用 os 可以指定項目對操作系統的兼容性要求。例如：

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

cpu

指定項目只能在特定的 CPU 體系上運行：

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

<!-- 一些三方庫或應用在內部處理時會依賴這些字段，使用時需要先安裝對應三方庫 -->

types 或 typings

指定 TypeScript 的類型定義的入口文件。例如：

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

unpkg

該字段應指向一文件，unpkg 稍後將為後者提供 CDN 支持，詳情參見

jsdelivr

與 unpkg 類似

browserslist

設置項目的瀏覽器兼容情況。babel 和 autoprefixer 等工具會根據該配置對代碼進行轉換。當然也可以使用 .browserslistrc 文件單獨配置。典型的：

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

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，來告知這些文件具有副作用，不能被剔除：

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

lint-staged

lint-staged 是用於對 git 暫存區文件進行操作的工具，可在代碼提交前執行 lint 校驗、類型檢查、圖片優化等操作，也通常配合 husky 等 git-hooks 工具一起使用。後者用於定義鈎子方法，並在 git 工作流中如 pre-commit，commit-msg 時觸發，可把 lint-staged 放到這些鈎子方法中（？？？）

全棧 , node.js , vite , webpack , 前端
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.