簡介
本文檔有所有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是這個東西的名字。注意：
- 不要把node或者js放在名字中。因為你寫了package.json它就被假定成為了js，不過你可以用”engine”字段指定一個引擎（見后文）。
- 這個名字會作為在URL的一部分、命令行的參數或者文件夾的名字。任何non-url-safe的字符都是不能用的。
- 這個名字可能會作為參數被傳入require()，所以它應該比較短，但也要意義清晰。
- 在你愛上你的名字之前，你可能要去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" : "project@hostname.com"
}
你可以指定一個或者指定兩個。如果你只想提供一個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" : "b@rubble.com"
, "url" : "http://barnyrubble.tumblr.com/"
}
或者可以把所有的東西都放到一個字符串里，npm會給你解析：
"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)
email和url在兩種形式中都是可選的。
也可以在你的npm用戶信息中設置一個頂級的maintainers字段。
files
files是一個包含項目中的文件的數組。如果命名了一個文件夾，那也會包含文件夾中的文件。（除非被其他條件忽略了）
你也可以提供一個.npmignore文件，讓即使被包含在files字段中得文件被留下。其實就像.gitignore一樣。
main
main字段配置一個文件名指向模塊的入口程序。如果你包的名字叫foo，然后用戶require("foo")，main配置的模塊的exports對象會被返回。
這應該是一個相對於根目錄的文件路徑。
對於大多數模塊，它是非常有意義的，其他的都沒啥。
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是要運行的命令。
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).
version必須完全和version一致>version必須比version大>=version同上<version同上<=version同上~version大約一樣，見semver(7)1.2.x1.2.0, 1.2.1, 等，但不包括1.3.0http://...見下文’依賴URL’*所有""空，同*version1 - version2同>=version1 <=version2.range1 || range2二選一。git...見下文’依賴Git URL’user/repo見下文’GitHub URLs’
比如下面都是合法的：
{ "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中。
這些東西會在執行npm link或者npm install的時候初始化，並可以像其他npm配置參數一樣管理。詳見npm-config(7)。
對於非特定平台的構建步驟，比如需要編譯CoffeeScript，可以用prepublish腳本去實現，並把它依賴的包放在devDependency中。（譯者注：prepublish定義了在執行npm publish的時候先行執行的腳本）
比如：
{ "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可能會產生下面的依賴關系
├── tea-latte@1.3.5
└── tea@2.2.0
試圖初始化另一個有會沖突的依賴的插件將導致一個錯誤。因此，確保你的插件的需求約束越弱越好，而不要去把它鎖定到一個特定的版本。
假設這個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)有可以被重寫的列表。
未經允許不得轉載：前端里 » npm的package.json字段含義中文文檔