package.json配置詳解

name

在大多數在你的package.json重要的事情是名稱和版本字段。這些其實是必需的，沒有它們，您的軟件包將沒法安裝。名稱和版本一塊兒構成一個標識符，該標識符被認爲是徹底惟一的。對軟件包的更改應與版本的更改同時進行。

名字就是你的名字。

一些規則：

• 名稱必須少於或等於214個字符。這包括範圍包的範圍。
• 名稱不能以點或下劃線開頭。
• 新軟件包名稱中不得包含大寫字母。
• 該名稱最終成爲URL，命令行參數和文件夾名稱的一部分。所以，該名稱不能包含任何非URL安全的字符。

一些技巧：

• 不要使用與核心Node模塊相同的名稱。
• 不要在名稱中添加「 js」或「 node」。假設它是js，由於您正在編寫package.json文件，而且可使用「 engines」字段指定引擎。（見下文。）
• 該名稱可能會做爲參數傳遞給require（），所以它應該簡短一些，但也應具備合理的描述性。
• 您可能須要檢查npm註冊表，以查看是否已經有該名稱的東西，而後再附加它。https://www.npmjs.com/

名稱能夠可選地以範圍爲前綴，例如@myorg/mypackage。請參閱 npm-scope以獲取更多詳細信息。

version

在大多數在你的package.json重要的事情是名稱和版本字段。這些其實是必需的，沒有它們，您的軟件包將沒法安裝。名稱和版本一塊兒構成一個標識符，該標識符被認爲是徹底惟一的。對軟件包的更改應與版本的更改同時進行。

版本必須能夠由node-semver解析 ，它與npm捆綁在一塊兒做爲依賴項。（npm install semver本身使用）。

有關版本號和範圍的更多信息，請參見semver。

description

在其中添加描述。這是一個字符串。如中所列，這能夠幫助人們發現您的包

keywords

在其中放入關鍵字。它是一個字符串數組。這能夠幫助人們發現您的軟件包

homepage

項目首頁的網址

bugs

項目的問題跟蹤器的URL和/或應向其報告問題的電子郵件地址。這些對於遇到您的包問題的人頗有幫助。

它看起來應該像這樣：

{
  "url": "https://github.com/owner/project/issues",
  "email": "project@hostname.com"
}

您能夠指定一個或兩個值。若是您只想提供一個url，則能夠將「 bugs」的值指定爲簡單字符串而不是對象。

若是提供了URL，則該npm bugs命令將使用它。

license

您應該爲包指定許可證，以便人們知道如何使用它們以及您對該包裹施加的任何限制。

若是您使用的是通用許可證，例如BSD-2-Clause或MIT，請爲所使用的許可證添加當前SPDX許可證標識符，以下所示：

{ "license" : "BSD-3-Clause" }

您能夠查看SPDX許可證ID的完整列表。理想狀況下，您應該選擇通過 OSI批准的產品。

若是您的軟件包已得到多個通用許可證的許可，請使用SPDX許可證表達式語法版本2.0字符串，以下所示：

{ "license" : "(ISC OR GPL-3.0)" }

若是使用的許可證還沒有分配SPDX標識符，或者使用的是自定義許可證，請使用以下所示的字符串值：

{ "license" : "SEE LICENSE IN <filename>" }

而後<filename>，在包的頂層添加一個名爲的文件。

一些舊軟件包使用許可證對象或包含許可證對象數組的「 licenses」屬性：

// Not valid metadata
{
  "license": {
    "type": "ISC",
    "url": "https://opensource.org/licenses/ISC"
  }
}
// Not valid metadata
{
  "licenses": [
    {
      "type": "MIT",
      "url": "https://www.opensource.org/licenses/mit-license.php"
    },
    {
      "type": "Apache-2.0",
      "url": "https://opensource.org/licenses/apache2.0.php"
    }
  ]
}

這些樣式現已棄用。而是使用SPDX表達式，以下所示：

{ "license": "ISC" }

{ "license": "(MIT OR Apache-2.0)" }

最後，若是您不但願以任何條款授予他人使用私有或未發佈軟件包的權利：

{ "license": "UNLICENSED" }

還考慮進行設置"private": true以防止意外發布。

author, contributors

「做者」是一我的。「貢獻者」是一羣人。「人員」是具備「名稱」字段以及（可選）「 url」和「 email」的對象，以下所示：

{
  "name": "Barney Rubble",
  "email": "b@rubble.com",
  "url": "http://barnyrubble.tumblr.com/"
}

或者，您能夠將全部內容縮短爲一個字符串，而後npm會爲您解析：

"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"

電子郵件和url都是可選的。

npm還會爲您的npm用戶信息設置一個頂級「 maintainers」字段。

files

可選的「files」字段是文件模式的數組，描述了將軟件包做爲依賴項安裝時要包括的條目。若是省略files數組，則除自動排除的文件外的全部內容都將包含在您的發佈中。若是在數組中命名文件夾，則該文件還將包括該文件夾中的文件（除非本節中的另外一條規則將忽略它們）。

您還能夠.npmignore在包的根目錄或子目錄中提供文件，以防止文件被包含。在程序包的根目錄下，它不會覆蓋「files」字段，但在子目錄中，它將覆蓋。該.npmignore文件的工做方式與同樣 .gitignore。若是有.gitignore文件但.npmignore缺乏文件，.gitignore則將使用的內容。

不管設置如何，老是會包含某些文件：

• package.json
• README
• CHANGES / CHANGELOG / HISTORY
• LICENSE / LICENCE
• NOTICE
• 「main」字段中的文件

README，CHANGES，LICENSE和NOTICE能夠有任何狀況下和延伸。

相反，某些文件老是被忽略：

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• .*.swp
• .DS_Store
• ._*
• npm-debug.log
• .npmrc
• node_modules
• config.gypi
• *.orig
• package-lock.json （改用收縮包裝）

main

模塊ID，它是程序的主要入口點。也就是說，若是您的包名爲foo，而且用戶先安裝它，而後執行 require("foo")，則將返回主模塊的導出對象。

這應該是相對於軟件包文件夾根目錄的模塊ID。

對於大多數模塊，擁有一個主腳本是最有意義的，而一般沒有太多其餘東西。

bin

許多軟件包都具備一個或多個要安裝到PATH中的可執行文件。npm使此操做很是容易（實際上，它使用此功能來安裝「 npm」可執行文件。）

要使用此功能，請bin在package.json中提供一個字段，該字段是命令名到本地文件名的映射。在安裝時，npm會將文件符號連接到 prefix/bin以進行全局安裝或./node_modules/.bin/本地安裝。

例如，myapp可能具備如下內容：

{
  "bin": {
    "myapp": "./cli.js"
  }
}

所以，當您安裝myapp時，它將建立從cli.js腳本到 的符號連接/usr/local/bin/myapp。

若是您只有一個可執行文件，而且其名稱應爲程序包的名稱，則只需將其提供爲字符串便可。例如：

{
  "name": "my-program",
  "version": "1.2.5",
  "bin": "./path/to/program"
}

將與此相同：

{
  "name": "my-program",
  "version": "1.2.5",
  "bin": {
    "my-program": "./path/to/program"
  }
}

請確保您引用的文件以bin開頭 #!/usr/bin/env node，不然腳本將在沒有node可執行文件的狀況下啓動！

man

指定要放置的單個文件或文件名數組，以供 man程序查找。

若是僅提供一個文件，則將其安裝爲來自的結果man <pkgname>，而無論其實際文件名如何。例如：

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": "./man/doc.1"
}

將連接./man/doc.1文件，使其成爲目標man foo

若是文件名不是以程序包名稱開頭的，則使用前綴。因此這：

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": [
    "./man/foo.1",
    "./man/bar.1"
  ]
}

將建立文件作man foo和man foo-bar。

手冊文件必須以數字結尾，.gz若是被壓縮，則必須之後綴結尾。該數字指示文件安裝在哪一個man節中。

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": [
    "./man/foo.1",
    "./man/foo.2"
  ]
}

將建立條目man foo和man 2 foo

directorys

CommonJS Packages規範詳細介紹了幾種使用directories 對象指示軟件包結構的方法。若是查看npm的package.json，則會看到它具備doc，lib和man的目錄。

lib

告訴人們您的lib大部分在哪裏。對於lib文件夾，沒有什麼特別的事情，但這是有用的元信息。

bin

若是在中指定bin目錄directories.bin，則將添加該文件夾中的全部文件。

因爲該bin指令的工做方式，同時指定 bin路徑和設置directories.bin是錯誤的。若是要指定單個文件，請使用bin，對於現有bin目錄中的全部文件，請使用directories.bin。

man

一個充滿man頁的文件夾。糖經過遍歷文件夾來生成「 man」數組。

doc

將markdown文件放在這裏

example

示例腳本

test

測試

repository

指定代碼所在的位置。這對想要貢獻的人頗有幫助。若是git repo在GitHub上，則該npm docs 命令將可以找到您。

像這樣作：

"repository": {
  "type": "git",
  "url": "https://github.com/npm/npm.git"
}

"repository": {
  "type": "svn",
  "url": "https://v8.googlecode.com/svn/trunk/"
}

該URL應該是可公開獲取（多是隻讀）的URL，能夠直接將其傳遞給VCS程序，而無需進行任何修改。它不該是您放入瀏覽器中的html項目頁面的url。它用於計算機。

對於GitHub，GitHub gist，Bitbucket或GitLab存儲庫，您可使用與如下相同的快捷方式語法npm install：

"repository": "npm/npm"

"repository": "github:user/repo"

"repository": "gist:11081aaa281"

"repository": "bitbucket:user/repo"

"repository": "gitlab:user/repo"

scripts

「 scripts」屬性是一個字典，其中包含在包的生命週期中的各個時間運行的腳本命令。關鍵是生命週期事件，該值是在該點運行的命令。

請參閱參考資料，npm-scripts以瞭解有關編寫程序包腳本的更多信息。

config

「 config」對象可用於設置軟件包腳本中使用的配置參數，這些配置腳本會在升級期間持續存在。例如，若是一個程序包具備如下內容：

{
  "name": "foo",
  "config": {
    "port": "8080"
  }
}

而後有一個「開始」命令，該命令隨後引用了 npm_package_config_port環境變量，那麼用戶能夠經過執行來覆蓋它npm config set foo:port 8001。

有關軟件包配置的更多信息，請參見npm-config和npm-scripts。

dependencies

依賴關係在一個簡單的對象中指定，該對象將程序包名稱映射到版本範圍。版本範圍是一個具備一個或多個以空格分隔的描述符的字符串。依賴關係也能夠經過tarball或git URL進行標識。

請不要在您的dependencies物體中放置測試線束或編譯器 。 請參閱devDependencies下面的。

有關指定版本範圍的更多詳細信息，請參見semver。

• version必須version徹底匹配
• >version 必須大於 version
• >=version 等等
• <version
• <=version
• ~version「大約等效於版本」請參見semver
• ^version「與版本兼容」請參見semver
• 1.2.x 1.2.0、1.2.1等，但不是1.3.0
• http://... 請參閱下面的「 URL做爲依賴項」
• * 匹配任何版本
• "" （只是一個空字符串）與 *
• version1 - version2與相同>=version1 <=version2。
• range1 || range2 若是知足range1或range2，則經過。
• git... 請參閱下面的「將Git URL做爲依賴項」
• user/repo 請參閱下面的「 GitHub URL」
• tag標記併發布爲tag See的特定版本npm-dist-tag
• path/path/path請參閱下面的本地路徑

例如，這些都是有效的：

{ "dependencies" :
  { "foo" : "1.0.0 - 2.9999.9999"
  , "bar" : ">=1.0.2 <2.1.2"
  , "baz" : ">1.0.2 <=2.3.4"
  , "boo" : "2.0.1"
  , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
  , "asd" : "http://asdf.com/asdf.tar.gz"
  , "til" : "~1.2"
  , "elf" : "~1.2.3"
  , "two" : "2.x"
  , "thr" : "3.3.x"
  , "lat" : "latest"
  , "dyl" : "file:../dyl"
  }
}

URL做爲依賴項

您能夠指定tarball URL代替版本範圍。

該壓縮包將在安裝時下載並本地安裝到您的軟件包中。

Git URL做爲依賴項

Git URL的形式爲：

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

<protocol>是如下之一git，git+ssh，git+http，git+https，或 git+file。

若是#<commit-ish>提供，它將用於精確克隆該提交。若是commit-ish的格式爲#semver:<semver>，<semver>能夠是任何有效的semver範圍或確切的版本，而且npm會在遠程存儲庫中查找與該範圍匹配的任何標記或引用，就像對註冊表依賴項同樣。若是未指定#<commit-ish>或#semver:<semver>，則master使用。

例子：

git+ssh://git@github.com:npm/npm.git#v1.0.27
git+ssh://git@github.com:npm/npm#semver:^5.0
git+https://isaacs@github.com/npm/npm.git
git://github.com/npm/npm.git#v1.0.27

GitHub網址

從1.1.65版本開始，您能夠將GitHub URL簡稱爲「 foo」：「 user / foo-project」。與git URL同樣，commit-ish能夠包含後綴。例如：

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "expressjs/express",
    "mocha": "mochajs/mocha#4727d357ea",
    "module": "user/repo#feature\/branch"
  }
}

本地路徑

從2.0.0版開始，您能夠提供包含軟件包的本地目錄的路徑。可使用npm install -S或 npm install --save使用如下任意形式保存本地路徑：

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

在這種狀況下，它們將被規範化爲相對路徑並添加到您的中 package.json。例如：

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

此功能對於本地脫機開發和建立須要npm安裝的測試頗有用，您不想在不打外部服務器的地方安裝npm，可是在將程序包發佈到公共註冊表時不該使用。

devDependencies

若是某人打算在程序中下載和使用您的模塊，那麼他們可能不但願或不須要下載並構建您使用的外部測試或文檔框架。

在這種狀況下，最好將這些其餘項目映射到一個devDependencies 對象中。

這些東西將在安裝時npm link或npm install 從軟件包的根目錄安裝，而且能夠像其餘任何npm配置參數同樣進行管理。有關npm-config更多信息，請參見。

對於不是特定於平臺的構建步驟（例如，將CoffeeScript或其餘語言編譯爲JavaScript），請使用prepare 腳原本執行此操做，並使所需的軟件包成爲devDependency。

例如：

{
  "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepare": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

該prepare腳本將在發佈以前運行，所以用戶可使用該功能而無需他們本身對其進行編譯。在開發人員模式下（即在本地運行npm install），它也會同時運行此腳本，以便您能夠輕鬆對其進行測試。

peerDependencies

在某些狀況下，您想表達軟件包與主機工具或庫的兼容性，而沒必要必定要require對此主機進行操做。一般將其稱爲插件。值得注意的是，您的模塊可能正在公開主機文檔預期和指定的特定接口。

例如：

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

這樣能夠確保您的軟件包tea-latte只能與主機軟件包的第二個主要版本一塊兒安裝tea。npm install tea-latte可能會產生如下依賴關係圖：

├── tea-latte@1.3.5
└── tea@2.2.0

注意：peerDependencies若是在依賴關係樹中未顯式依賴更高版本的npm版本1和2 ，它們將自動安裝。在npm的下一個主要版本（npm @ 3）中，將再也不是這種狀況。您將收到一條警告，提示您未安裝peerDependency。npms 1和2中的行爲常常使人困惑，很容易使您陷入依賴地獄，npm旨在儘量避免這種狀況。

嘗試安裝其餘要求衝突的插件會致使錯誤。所以，請確保您的插件要求儘量普遍，而且不要將其鎖定在特定的補丁程序版本中。

假設主機符合semver，則只有主機軟件包主要版本中的更改會破壞您的插件。所以，若是您使用過主機軟件包的每一個1.x版本，請使用"^1.0"或"1.x"表示這一點。若是您依賴1.5.2中引入的功能，請使用">= 1.5.2 < 2"。

bundledDependencies

這定義了一組軟件包名稱，這些軟件包名稱將在發佈軟件包時捆綁在一塊兒。

若是您須要在本地保留npm軟件包或經過單個文件下載得到它們，則能夠經過在bundledDependencies 數組中指定軟件包名稱並執行來將軟件包捆綁在tarball文件中npm pack。

例如：

若是咱們這樣定義package.json：

{
  "name": "awesome-web-framework",
  "version": "1.0.0",
  "bundledDependencies": [
    "renderized", "super-streams"
  ]
}

咱們能夠awesome-web-framework-1.0.0.tgz經過運行獲取文件npm pack。此文件包含的依賴關係renderized，並super-streams能夠經過執行安裝在一個新的項目npm install awesome-web-framework-1.0.0.tgz。

若是這是拼寫的"bundleDependencies"，那麼也很榮幸。

optionalDependencies

若是可使用依賴項，可是若是找不到或沒法安裝npm，則但願npm繼續進行，則能夠將其放在optionalDependencies 對象中。這是程序包名稱到版本或url的映射，就像 dependencies對象同樣。區別在於構建失敗不會致使安裝失敗。

處理依賴關係的缺失仍然是程序的責任。例如，以下所示：

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

中的條目optionalDependencies將覆蓋中的相同名稱的條目 dependencies，所以一般最好只放在一個位置。

engines

您能夠指定您的東西能夠在其上運行的node的版本：

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

而且，與依賴項同樣，若是您不指定版本（或者若是您指定「 *」做爲版本），那麼任何版本的節點均可以。

若是您指定「engines」字段，則npm將要求「node」在該列表中的某個位置。若是省略了「 engines」，那麼npm只會假設它能夠在node上運行。

您還可使用「engines」字段來指定哪些版本的npm可以正確安裝程序。例如：

{ "engines" : { "npm" : "~1.0.20" } }

除非用戶設置了engine-strictconfig標誌，不然此字段僅供參考，而且僅在將軟件包做爲依賴項安裝時才產生警告。

os

您能夠指定模塊將在哪些操做系統上運行：

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

您也能夠將操做系統列入黑名單而不是白名單，只需在黑名單的操做系統前面加上「！」便可：

"os" : [ "!win32" ]

主機操做系統由 process.platform

儘管沒有充分的理由這樣作，但容許將其列入黑名單和白名單。

cpu

若是您的代碼僅在某些cpu體系結構上運行，則能夠指定哪些體系結構。

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

像該os選項同樣，您也能夠將體系結構列入黑名單：

"cpu" : [ "!arm", "!mips" ]

主機架構由 process.arch

private

若是"private": true在package.json中設置，則npm將拒絕發佈它。

這是防止意外發布私有存儲庫的方法。若是要確保僅將給定的程序包發佈到特定的註冊表（例如，內部註冊表），請使用publishConfig下面描述的 字典registry在發佈時覆蓋config參數。

publishConfig

這是將在發佈時使用的一組配置值。若是要設置標籤，註冊表或訪問權限，這特別方便，這樣能夠確保給定的程序包不標記爲「最新」，不發佈到全局公共註冊表，或者默認狀況下做用域模塊是私有的。

能夠覆蓋任何配置值，可是出於發佈的目的，固然只有「標籤」，「註冊表」和「訪問」可能很重要。

請參閱npm-config以查看能夠覆蓋的配置選項列表。