文檔複製 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
@scope/
for 範圍包)。.
)或下劃線(_
)開頭。Tipsgithub
Node.js
核心模塊相同的名字。js
或者 node
單詞。require()
調用裏。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字段必須是如下之一:
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
模塊語法的模塊,但僅指向目標環境支持的語法功能。 完整的描述在這裏。
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。
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
字段。