文件 package.json 的說明文檔

時間 2019-11-05

標籤文件 package.json package json 說明文檔欄目 JavaScript 简体版

原文原文鏈接

文檔複製 yarnpkg 官方文檔，並非徹底複製，增長了一些內容和一些描述，做爲筆記存儲。你也能夠參考 npm documentation, std-pkg, clean-publish, package-json-validator, cosmiconfig, rc。html

歡迎來點 Star： github.com/jaywcjlove/…node

重要字段

你的 package.json 中最重要的兩個字段是 name 和 version，若是沒有它們，您的包將沒法安裝。 name 和version 字段一塊兒用於建立惟一ID。linux

`name`

{
  "name": "my-awesome-package"
}
複製代碼

這是您的 包 的名稱。它在URL中使用，做爲參數命令行，以及 node_modules 中的目錄名。webpack

yarn add [包名]
# or
npm install [包名]
複製代碼

node_modules/[包名]
複製代碼

https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz
複製代碼

規則git

必須小於或等於214個字符（包括 @scope/ for 範圍包）。
不能以點（.）或下劃線（_）開頭。
名稱中不得包含大寫字母。
必須僅使用URL安全字符。

Tipsgithub

不要使用和 Node.js 核心模塊相同的名字。
不要在名字裏包含 js 或者 node 單詞。
短小精悍，讓人看到名字就大概瞭解包的功能，記住它也會被用在 require() 調用裏。
保證名字在 npm registry 裏是惟一的。

`version`

包的當前版本，嚴格遵循 Semantic Versioning 2.0.0 語義化版本規範。web

{
  "version": "1.0.0"
}
複製代碼

信息類字段

`description`

Description 是幫助使用者瞭解包的功能的字符串，包管理器也會把這個字符串做爲搜索關鍵詞。typescript

{
  "description": "個人包的概要簡短描述"
}
複製代碼

`keywords`

關鍵字是一個字符串數組，當在包管理器裏搜索包時頗有用。npm

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}
複製代碼

`license`

全部包都應該指定許可證，以便讓用戶瞭解他們是在什麼受權下使用此包，以及此包還有哪些附加限制。json

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}
複製代碼

鼓勵使用開源 (OSI-approved) 許可證，除非你有特別的緣由不用它。若是你開發的包是你工做的一部分，最好和公司討論後再作決定。

license字段必須是如下之一:

若是你使用標準的許可證，須要一個有效地 SPDX 許可證標識。
若是你用多種標準許可證，須要有效的 SPDX 許可證表達式2.0語法表達式。
若是你使用非標準的許可證，一個 SEE LICENSE IN <文件名> 字符串指向你的包裏頂級目錄的一個 <文件名>。
若是你不想在任何條款下受權其餘人使用你的私有或未公開的包，一個 UNLICENSED 字符串。

連接類字段

各類指向項目文檔、issues 上報，以及代碼託管網站的連接字段。

`homepage`

是包的項目主頁或者文檔首頁。

{
  "homepage": "https://your-package.org"
}
複製代碼

`bugs`

問題反饋系統的 URL，或者是 email 地址之類的連接。用戶經過該途徑向你反饋問題。

{
  "bugs": "https://github.com/user/repo/issues"
}
複製代碼

`repository`

是代碼託管的位置。

{
  "repository": { "type": "git", "url": "https://github.com/user/repo.git" },
  "repository": "github:user/repo",
  "repository": "gitlab:user/repo",
  "repository": "bitbucket:user/repo",
  "repository": "gist:a1b2c3d4e5f"
}
複製代碼

The repository is the location where the actual code for your package lives.

項目維護類字段

項目的維護者。

`author`

做者信息，一我的。

{
  "author": { "name": "Your Name", "email": "you@example.com", "url": "http://your-website.com" },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}
複製代碼

`contributors`

貢獻者信息，可能不少人。

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}
複製代碼

文件類信息

指定包含在項目中的文件，以及項目的入口文件。

`files`

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

項目包含的文件，能夠是單獨的文件、整個文件夾，或者通配符匹配到的文件。

`main`

項目的入口文件。

{
  "main": "filename.js"
}
複製代碼

`bin`

隨着項目一塊兒被安裝的可執行文件。

{
  "bin": "bin.js",
  "bin": {
    "命令名稱": "bin/命令路徑/命令名稱.js",
    "other-command": "bin/other-command"
  }
}
複製代碼

`man`

項目的入口文件。

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}
複製代碼

`directories`

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}
複製代碼

當你的包安裝時，你能夠指定確切的位置來放二進制文件、man pages、文檔、例子等。

`types`

這是一個只在 TypeScript 中生效的字段，若是您的包有一個 main.js 文件，您還須要在 package.json 文件中指明主聲明文件。將 types 屬性設置爲指向 bundled 的聲明文件。例如：

{
  "types": "./lib/main.d.ts",
}
複製代碼

若是您的主聲明文件名爲 index.d.ts 而且位於包的根目錄（index.js旁邊），則不須要標記 types 屬性，建議這樣作。

打包包字段

`module`

pkg.module 將指向具備 ES2015 模塊語法的模塊，但僅指向目標環境支持的語法功能。完整的描述在這裏。

支持：rollup, webpack

`browser`

字段由模塊做者提供，做爲 JavaScript 包或組件工具的提示，用於打包模塊以供客戶端使用。提案就在這裏。

`esnext`

完整的提案在這裏。簡短說明：

esnext：ES模塊中使用階段4功能（或更舊版本）的源代碼，未編譯。
main：指向一個CommonJS模塊（或UMD模塊），其 JavaScript 與 Node.js 當前能夠處理的同樣現代。
大多數 module 用例應該能夠經過 esnext 處理。
browser 能夠經過 esnext 的擴展版原本處理

{
  "main": "main.js",
  "esnext": {
    "main": "main-esnext.js",
    "browser": "browser-specific-main-esnext.js"
  }
}
複製代碼

另請參閱：Delivering untranspiled source code via npm

任務類字段

包裏還能夠包含一些可執行腳本或者其餘配置信息。

`scripts`

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}
複製代碼

腳本是定義自動化開發相關任務的好方法，好比使用一些簡單的構建過程或開發工具。在 scripts 字段裏定義的腳本，能夠經過 yarn run <script> 命令來執行。例如，上述 build-project 腳本能夠經過 yarn run build-project 調用，並執行 node build-project.js。

有一些特殊的腳本名稱。若是定義了 preinstall 腳本，它會在包安裝前被調用。出於兼容性考慮，install、postinstall 和 prepublish 腳本會在包完成安裝後被調用。

start 腳本的默認值爲 node server.js。

參考文檔：npm docs

特定的 `scripts`

對於如下腳本，npm 支持 package.json 文件的 scripts 默認命令字段：

prepublish: 在打包併發布包以前運行，以及在沒有任何參數的本地 npm 安裝以前運行。（見下文）
prepare: 在打包和發佈包以前運行，在沒有任何參數的本地 npm install 上運行，以及安裝 git 依賴項時（見下文）。這是在 preublish 以後運行，可是在 preublishOnly 以前運行。
prepublishOnly: 在包準備和打包以前運行，僅限於npm發佈。（見下文。）
prepack: 在打包 tarball 以前運行（在 npm pack，npm publish，以及安裝 git 依賴項時）
postpack: 在生成 tarball 以後運行並移動到其最終目標。
publish, postpublish: 在包發佈後運行。
preinstall: 在安裝軟件包以前運行。
install, postinstall: 安裝包後運行。
preuninstall, uninstall: 在卸載軟件包以前運行。
postuninstall: 在卸載軟件包以後運行。
preversion: 在改變包版本以前運行。
version: 改變包版本後運行，但提交以前。
postversion: 改變包版本後運行，而後提交。
pretest, test, posttest: 由 npm test 命令運行。
prestop, stop, poststop: 由 npm stop 命令運行。
prestart, start, poststart: 由 npm start 命令運行。
prerestart, restart, postrestart: 由 npm restart 命令運行。注意：若是沒有提供重啓腳本，npm restart 將運行 stop 和start 腳本。
preshrinkwrap, shrinkwrap, postshrinkwrap: 由 npm shrinkwrap 命令運行。

參考文檔：npm docs.

`config`

{
  "config": {
    "port": "8080"
  }
}
複製代碼

配置你的腳本的選項或參數。

依賴描述類字段

你的包極可能依賴其餘包。你能夠在你的 package.json 文件裏指定那些依賴。

`dependencies`

這些是你的包的開發版和發佈版都須要的依賴。

{
  "dependencies": {
    "package-1": "^3.1.4",
    "package-2": "file:./path/to/dir"
  }
}
複製代碼

你能夠指定一個確切的版本、一個最小的版本 (好比 >=) 或者一個版本範圍 (好比 >= ... <)。
包也能夠指向本地的一個目錄文件夾。

`devDependencies`

這些是隻在你的包開發期間須要，可是生產環境不會被安裝的包。

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}
複製代碼

`peerDependencies`

平行依賴容許你說明你的包和其餘包版本的兼容性。

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}
複製代碼

`optionalDependencies`

可選依賴能夠用於你的包，但不是必需的。若是可選包沒有找到，安裝還能夠繼續。

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}
複製代碼

`bundledDependencies`

打包依賴是發佈你的包時將會一塊兒打包的一個包名數組。

{
  "bundledDependencies": [
    "package-4"
  ]
}
複製代碼

系統

你能夠提供和你的包關聯的系統級的信息，好比操做系統兼容性之類。

`engines`

指定使用你的包客戶必須使用的版本，這將檢查 process.versions 以及當前 yarn 版本。

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}
複製代碼

此檢查遵照正常的 semver 規則，但有一個例外。它容許預發佈版本匹配未明確指定預發佈的 semver。例如，1.4.0-rc.0 匹配 >=1.3.0，但它與典型的 semver 檢查不匹配。

`os`

此選項指定你的包的操做系統兼容性，它會檢查 process.platform。

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}
複製代碼

`cpu`

使用這個選項指定你的包將只能在某些 CPU 體系架構上運行，這會檢查 process.arch。

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}
複製代碼

發佈

`private`

{
  "private": true
}
複製代碼

若是你不想你的包發佈到包管理器(npm 或者私有包管理)，設置爲 true。

`publishConfig`

這些配置值將在你的包發佈時使用。好比，你能夠給包打標籤。

{
  "publishConfig": {
    "registry": "https://registry.npm.taobao.org"
  }
}
複製代碼

這是一組將在發佈時使用的配置值。若是要設置標記，註冊表或訪問權限，則特別方便，以便確保給定的包未標記爲 latest，發佈到全局公共 registry 或默認狀況下，做用域模塊(@scoped)是私有的。

能夠覆蓋任何配置值，但只有 tag，registry 和 access 可能對於發佈而言很重要，npm-config。

Yarn

`flat`

若是你的包只容許給定依賴的一個版本，你想強制和命令行上 yarn install --flat 相同的行爲，把這個值設爲 true。

{
  "flat": true
}
複製代碼

請注意，若是你的 package.json 包含 "flat": true 而且其它包依賴你的包 (好比你在構建一個庫，而不是應用)，其它那些包也須要在它們的 package.json 加上 "flat": true，或者在命令行上用 yarn install --flat 安裝。

`resolutions`

{
  "resolutions": {
    "transitive-package-1": "0.0.29",
    "transitive-package-2": "file:./local-forks/transitive-package-2",
    "dependencies-package-1/transitive-package-3": "^2.1.1"
  }
}
複製代碼

容許您覆蓋特定嵌套依賴項的版本。有關完整規範，請參見選擇性版本解析 RFC。

注意，yarn install --flat 命令將會自動在 package.json 文件里加入 resolutions 字段。