文件 package.json 的說明文檔

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

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

重要字段

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

name

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

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

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

node_modules/[包名]
複製代碼

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

規則

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

Tips

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

version

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

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

信息類字段

description

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

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

keywords

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

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

license

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

{
  "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 字段。