簡介
本文檔有所有package.json中必要的配置。它必須是真正的json，而不是js對象。
本文檔中描述的很多行為都受npm-config(7)的影響。
默認值
npm會根據包內容設置一些默認值。
復制代碼 代碼如下:"scripts": {"start": "node server.js"}
如果包的根目錄有server.js文件，npm會默認將start命令設置為node server.js。
"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}
如果包的根目錄有wscript文件，npm會默認將preinstall命令用node-waf進行編譯。
"scripts":{"preinstall": "node-gyp rebuild"}
如果包的根目錄有binding.gyp文件，npm會默認將preinstall命令用node-gyp進行編譯。
"contributors": [...]
如果包的根目錄有AUTHORS文件，npm會默認逐行按Name <email> (url)格式處理，郵箱和url是可選的。#號和空格開頭的行會被忽略。
name
在package.json中最重要的就是name和version字段。他們都是必須的，如果沒有就無法install。name和version一起組成的標識在假設中是唯一的。改變包應該同時改變version。
name是這個東西的名字。注意：
1.不要把node或者js放在名字中。因為你寫了package.json它就被假定成為了js，不過你可以用”engine”字段指定一個引擎（見後文）。
2.這個名字會作為在URL的一部分、命令行的參數或者文件夾的名字。任何non-url-safe的字符都是不能用的。
3.這個名字可能會作為參數被傳入require()，所以它應該比較短，但也要意義清晰。
4.在你愛上你的名字之前，你可能要去npm registry查看一下這個名字是否已經被使用了。http://registry.npmjs.org/
version
在package.json中最重要的就是name和version字段。他們都是必須的，如果沒有就無法install。name和version一起組成的標識在假設中是唯一的。改變包應該同時改變version。
version必須能被node-semver解析，它被包在npm的依賴中。（要自己用可以執行npm install semver）
可用的“數字”或者“范圍”見semver(7).
description
放簡介，字符串。方便屌絲們在npm search中搜索。
keywords
關鍵字，數組、字符串。還是方便屌絲們在npm search中搜索。
homepage
項目官網的url。
注意：這和“url”不一樣。如果你放一個“url”字段，registry會以為是一個跳轉到你發布在其他地方的地址，然後喊你滾粗。
嗯，滾粗，沒開玩笑。
bugs
你項目的提交問題的url和（或）郵件地址。這對遇到問題的屌絲很有幫助。
差不多長這樣：
復制代碼 代碼如下:
{ "url" : "http://github.com/owner/project/issues"
, "email" : "[email protected]"
}
你可以指定一個或者指定兩個。如果你只想提供一個url，那就不用對象了，字符串就行。
如果提供了url，它會被npm bugs命令使用。
license
你應該要指定一個許可證，讓人知道使用的權利和限制的。
最簡單的方法是，假如你用一個像BSD或者MIT這樣通用的許可證，就只需要指定一個許可證的名字，像這樣：
復制代碼 代碼如下:
{ "license" : "BSD" }
如果你又更復雜的許可條件，或者想要提供給更多地細節，可以這樣:
復制代碼 代碼如下:
"licenses" : [
{ "type" : "MyLicense"
, "url" : "http://github.com/owner/project/path/to/license"
}
]
在根目錄中提供一個許可證文件也蠻好的。
people fields: author, contributors
author是一個人。contributors是一堆人的數組。person是一個有name字段，可選的有url、email字段的對象，像這樣：
復制代碼 代碼如下:
{ "name" : "Barney Rubble"
, "email" : "[email protected]"
, "url" : "http://barnyrubble.tumblr.com/"
}
或者可以把所有的東西都放到一個字符串裡，npm會給你解析：
復制代碼 代碼如下:
"Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)
email和url在兩種形式中都是可選的。
也可以在你的npm用戶信息中設置一個頂級的maintainers字段。
files
files是一個包含項目中的文件的數組。如果命名了一個文件夾，那也會包含文件夾中的文件。（除非被其他條件忽略了）
你也可以提供一個.npmignore文件，讓即使被包含在files字段中得文件被留下。其實就像.gitignore一樣。
main
main字段是一個模塊ID，它是一個指向你程序的主要項目。就是說，如果你包的名字叫foo，然後用戶安裝它，然後require("foo")，然後你的main模塊的exports對象會被返回。
這應該是一個相對於根目錄的模塊ID。
對於大多數模塊，它是非常有意義的，其他的都沒啥。
bin
很多包都有一個或多個可執行的文件希望被放到PATH中。npm讓媽媽再也不用擔心了（實際上，就是這個功能讓npm可執行的）。
要用這個功能，給package.json中的bin字段一個命令名到文件位置的map。初始化的時候npm會將他鏈接到prefix/bin（全局初始化）或者./node_modules/.bin/（本地初始化）。
比如，npm有：
復制代碼 代碼如下:
{ "bin" : { "npm" : "./cli.js" } }
所以，當你初始化npm，它會創建一個符號鏈接到cli.js腳本到/usr/local/bin/npm。
如果你只有一個可執行文件，並且名字和包名一樣。那麼你可以只用一個字符串，比如：
復制代碼 代碼如下:
{ "name": "my-program"
, "version": "1.2.5"
, "bin": "./path/to/program" }
結果和這個一樣：
復制代碼 代碼如下:
{ "name": "my-program"
, "version": "1.2.5"
, "bin" : { "my-program" : "./path/to/program" } }
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 foo就可以用到./man/doc.1文件了。
如果文件名不是以包名開頭，那麼它會被冠以前綴，下面的：
復制代碼 代碼如下:
{ "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創建文件。
man文件需要以數字結束，然後可選地壓縮後以.gz為後綴。The number dictates which man section the file is installed into.
復制代碼 代碼如下:
{ "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創建。
directories
CommonJS Packages規范說明了幾種方式讓你可以用directorieshash標示出包得結構。如果看一下npm's package.json，你會看到有directories標示出doc, lib, and man。
在未來，這個信息可能會被用到。
directories.lib
告訴屌絲們你的庫文件夾在哪裡。目前沒有什麼特別的東西需要用到lib文件夾，但確實是重要的元信息。
directories.bin
如果你指定一個“bin”目錄，然後在那個文件夾中得所有文件都會被當做”bin”字段使用。
如果你已經指定了“bin”字段，那這個就無效。
directories.man
一個放滿man頁面的文件夾。貼心地創建一個“man”字段。
A folder that is full of man pages. Sugar to generate a “man” array by
walking the folder.
directories.doc
將markdown文件放在這裡。最後，這些會被很好地展示出來，也許，某一天。
Put markdown files in here. Eventually, these will be displayed nicely,
maybe, someday.
directories.example
將事例腳本放在這裡。某一天，它可能會以聰明的方式展示出來。
repository
指定你的代碼存放的地方。這個對希望貢獻的人有幫助。如果git倉庫在github上，那麼npm docs命令能找到你。
這樣做：
復制代碼 代碼如下:
"repository" :
{ "type" : "git"
, "url" : "http://github.com/isaacs/npm.git"
}
"repository" :
{ "type" : "svn"
, "url" : "http://v8.googlecode.com/svn/trunk/"
}
URL應該是公開的（即便是只讀的）能直接被未經過修改的版本控制程序處理的url。不應該是一個html的項目頁面。因為它是給計算機看的。
scripts
“scripts”是一個由腳本命令組成的hash對象，他們在包不同的生命周期中被執行。key是生命周期事件，value是要運行的命令。
參見 npm-scripts(7)
config
“config” hash可以用來配置用於包腳本中的跨版本參數。在實例中，如果一個包有下面的配置：
復制代碼 代碼如下:
{ "name" : "foo"
, "config" : { "port" : "8080" } }
然後有一個“start”命令引用了npm_package_config_port環境變量，用戶可以通過npm config set foo:port 8001來重寫他。
參見 npm-config(7) 和 npm-scripts(7)。
dependencies
依賴是給一組包名指定版本范圍的一個hash。這個版本范圍是一個由一個或多個空格分隔的字符串。依賴還可以用tarball或者git URL。
請不要將測試或過渡性的依賴放在dependencieshash中。見下文的devDependencies。
詳見semver(7).
1.version 必須完全和version一致
2.>version 必須比version大
3.>=version 同上
4.<version 同上
5.<=version 同上
6.~version 大約一樣，見semver(7)
7.1.2.x 1.2.0, 1.2.1, 等，但不包括1.3.0
8.http://... 見下文'依賴URL'
9.* 所有
10."" 空，同*
11.version1 - version2 同 >=version1 <=version2.
12.range1 || range2 二選一。
13.git... 見下文'依賴Git URL'
14.user/repo 見下文'GitHub URLs'
15.比如下面都是合法的：
復制代碼 代碼如下:
{ "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"
}
}
依賴URL
可以指定一個tarball URL，這個tarball將在包被初始化的時候下載並初始化。
依賴Git URL
Git urls 可以是下面幾種形式：
復制代碼 代碼如下:
git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish
commit-ish是可以被git checkout的任何tag、sha或者branch。默認為master。
GitHub URLs
1.1.65版後，你可以僅僅用“user/foo-project”引用GitHub urls，比如：
復制代碼 代碼如下:
{
"name": "foo",
"version": "0.0.0",
"dependencies": {
"express": "visionmedia/express"
}
}
devDependencies
如果有人計劃在他們的程序中下載並使用你的模塊，那麼他們可能不想或者不需要去下載並構建你使用的外部測試或者文檔框架。
在這種情況下，它最好把這些附屬的項目列示在devDependencies hash中。
這些東西會在根目錄執行npm link或者npm install的時候初始化，並可以像其他npm配置參數一樣管理。詳見npm-config(7)。
對於非特定平台的構建步驟，比如編譯CoffeeScript或者其他語言到Javascript，用prepublish腳本去實現並把他放在devDependency中。
比如：
復制代碼 代碼如下:
{ "name": "ethopia-waza",
"description": "a delightfully fruity coffee varietal",
"version": "1.2.3",
"devDependencies": {
"coffee-script": "~1.6.3"
},
"scripts": {
"prepublish": "coffee -o lib/ -c src/waza.coffee"
},
"main": "lib/waza.js"
}
prepublish腳本會在publishing前運行，這樣用戶就不用自己去require來編譯就能使用。並且在開發模式中（比如本地運行npm install）會運行這個腳本以便更好地測試。
peerDependencies
在一些場景中，如在一個host中不必須進行require時候，你想表現你的package與一個host工具或者庫的兼容關鍵。這一般用來引用插件。尤其是你的模塊可能要暴露一個特定的接口，並由host文檔來預期和指定。
比如：
復制代碼 代碼如下:
{
"name": "tea-latte",
"version": "1.3.5"
"peerDependencies": {
"tea": "2.x"
}
}
這能保證你的package可以只和tea的2.x版本一起初始化。npm install tea-latte可能會產生下面的依賴關系
復制代碼 代碼如下:
├── [email protected]
└── [email protected]
試圖初始化另一個有會沖突的依賴的插件將導致一個錯誤。因此，確保你的插件的需求約束越弱越好，而不要去把它鎖定到一個特定的版本。
假設這個host遵守semver規范，只改變這個package的主版本會打破你的插件。因此，如果你在package中用過每個1.x版本，就用”^1.0″或者”1.x”來表示。如果你依賴於功能介紹1.5.2，用”>= 1.5.2 < 2″。
bundledDependencies
一組包名，他們會在發布的時候被打包進去。
拼成"bundleDependencies"（缺d）也可以。
optionalDependencies
如果一個依賴可用，但你希望在它安裝錯誤的時候npm也能繼續初始化，那麼你可以把它放在optionalDependencies hash中。這是一個包名到版本或者url的map，就像dependencies hash一樣。只是它運行錯誤。
處理缺乏依賴也是你的程序的責任。比如像這樣：
復制代碼 代碼如下:
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" } }
並且，像dependensies一樣，如果你不指定版本或者指定“*”作為版本，那麼所有版本的node都可以。
如果指定一個“engines”字段，那麼npm會需要node在裡面，如果“engines”被省略，npm會假定它在node上工作。
你也可以用“engines”字段來指定哪一個npm版本能更好地初始化你的程序，如：
復制代碼 代碼如下:
{ "engines" : { "npm" : "~1.0.20" } }
記住，除非用戶設置engine-strict標記，這個字段只是建議值。
engineStrict
如果你確定你的模塊一定不會運行在你指定版本之外的node或者npm上，你可以在package.json文件中設置"engineStrict":true。它會重寫用戶的engine-strict設置。
除非你非常非常確定，否則不要這樣做。如果你的engines hash過度地限制，很可能輕易讓自己陷入窘境。慎重地考慮這個選擇。如果大家濫用它，它會再以後的npm版本中被刪除。
os
你可以指定你的模塊要運行在哪些操作系統中：
復制代碼 代碼如下:
"os" : [ "darwin", "linux" ]
你也可以用黑名單代替白名單，在名字前面加上“!”就可以了：
復制代碼 代碼如下:
"os" : [ "!win32" ]
操作系統用process.platform來探測。
雖然沒有很好地理由，但它是同時支持黑名單和白名單的。
cpu
如果你的代碼只能運行在特定的cpu架構下，你可以指定一個：
復制代碼 代碼如下:
"cpu" : [ "x64", "ia32" ]
就像os選項，你也可以黑一個架構：
復制代碼 代碼如下:
"cpu" : [ "!arm", "!mips" ]
cpu架構用process.arch探測。
preferGlobal
如果包主要是需要全局安裝的命令行程序，就設置它為true來提供一個warning給只在局部安裝的人。
它不會真正的防止用戶在局部安裝，但如果它沒有按預期工作它會幫助防止產生誤會。
private
如果你設置"private": true，npm就不會發布它。
這是一個防止意外發布私有庫的方式。如果你要確定給定的包是只發布在特定registry（如內部registry）的，用publishConfighash的描述來重寫registry的publish-time配置參數。
publishConfig
這是一個在publish-time使用的配置集合。當你想設置tag或者registry的時候它非常有用，所以你可以確定一個給定的包沒有打上“lastest”的tag或者被默認發布到全局的公開registry。
任何配置都可以被重寫，但當然可能只有“tag”和“registry”與發布的意圖有關。
參見npm-config(7)有可以被重寫的列表。