原文鏈接：http://www.mujiang.info/translation/npmjs/files/package.json.html

DESCRIPTION

本文檔有所有package.json中必要的配置假残。它必須是真正的json缭贡，而不是js對象。
本文檔中描述的很多行為都受npm-config(7)的影響辉懒。

一阳惹、name

在package.json中 最重要 的就是name和version字段。
他們都是必須的眶俩，如果沒有就無法install穆端。
name和version一起組成的標(biāo)識在假設(shè)中是唯一的。
改變包應(yīng)該同時(shí)改變version仿便。
name是這個(gè)東西的名字体啰。

注意：不要把node或者js放在名字中。因?yàn)槟銓懥藀ackage.json它就被假定成為了js嗽仪，不過你可以用"engine"字段指定一個(gè)引擎（見后文）荒勇。

這個(gè)名字會作為在URL的一部分、命令行的參數(shù)或者文件夾的名字闻坚。任何non-url-safe的字符都是不能用的沽翔。

這個(gè)名字可能會作為參數(shù)被傳入require()，所以它應(yīng)該比較短窿凤，但也要意義清晰仅偎。

在命名你的name之前，你可能要去npm registry查看一下這個(gè)名字是否已經(jīng)被使用了雳殊。 http://registry.npmjs.org/

二橘沥、version

version必須能被 node-semver解析，它被包在npm的依賴中夯秃。（要自己用可以執(zhí)行npm install semver）
更多可用的“數(shù)字”或者“范圍”見semver(7).

三座咆、scripts

存放 npm腳本的地方,npm run XXX，鍵值對形式存在

image.png

參見 npm-scripts(7)

四仓洼、dependencies

你的項(xiàng)目依賴的其他的第三方包。

請不要將測試或過渡性的依賴放在dependencies中。
見下文的devDependencies

1椎椰、波浪符號（~）：更新到當(dāng)前minor version（也就是中間的那位數(shù)字）中最新的版本宦棺。

body-parser:~1.15.2 --> 1.15.X ，但不會更新到： 1.16.0

2箕戳、插入符號（^）：更新到當(dāng)前major version（也就是第一位數(shù)字）中最新的版本某残。

bluebird:^3.3.4 --> 3.X.X, 但不會自動更新到4.0.0。

比如下面都是合法的：

{ 
 "devDependencies": {
    "acorn": "~0.6.0",
    "baconjs": "^0.7.43",
    "bluebird": "^2.9.2",
    "body-parser": "^1.10.2",
    "browserify": "^8.1.1",
    "cli-table": "~0.3.1",
    "co": "^4.2.0",
  }
}

五漂羊、devDependencies

僅在開發(fā)環(huán)境下使用的依賴包驾锰，放在devDependencies中。

線上發(fā)布時(shí)走越，如果dev依賴中的包不需要椭豫，那么可以執(zhí)行：
npm prune --production 來刪除已安裝的dev依賴包，以減少項(xiàng)目體積旨指。

對于構(gòu)建步驟赏酥，比如需要編譯CoffeeScript，可以用prepublish腳本去實(shí)現(xiàn)谆构，并把它依賴的包放在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"
}

六、optionalDependencies

如果一個(gè)依賴可用搬素，但你希望在它安裝錯(cuò)誤的時(shí)候npm也能繼續(xù)初始化呵晨，那么你可以把它放在optionalDependencieshash中魏保。

線上發(fā)布時(shí)可以選擇不安裝此目錄下的依賴：
npm install --no-optional

處理缺乏依賴也是你的程序的責(zé)任。比如像這樣：

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中同名的項(xiàng)摸屠，所以通常比只放在一個(gè)地方好谓罗。

七、bundledDependencies

一組包名季二，他們會在發(fā)布的時(shí)候被打包進(jìn)去檩咱。
拼成"bundleDependencies"
（缺d）也可以。

八胯舷、keywords

放簡介刻蚯，字符串。方便在 npm search中搜索桑嘶。

九炊汹、homepage

一般放這個(gè)項(xiàng)目的 git地址

十、bugs

你項(xiàng)目的提交問題的url和（或）郵件地址不翩。

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

你可以指定一個(gè)或者兩個(gè)兵扬。如果你只想提供一個(gè)url，那就直接用字符串口蝠。
如果提供了url器钟，它會被npm bugs命令使用。

十一妙蔗、license

你應(yīng)該要指定一個(gè)許可證傲霸，讓人知道使用的權(quán)利和限制的。
最簡單的方法是眉反，假如你用一個(gè)像BSD或者M(jìn)IT這樣通用的許可證昙啄，就只需要指定一個(gè)許可證的名字，像這樣：

{ "license" : "BSD" }

如果你有更復(fù)雜的許可條件寸五，或者想要提供給更多地細(xì)節(jié)梳凛，可以這樣:

"licenses" : [ 
   { 
       "type" : "MyLicense" , 
       "url" : "http://github.com/owner/project/path/to/license" 
   }
]

在根目錄中提供一個(gè)許可證文件也蠻好的。
people fields: author, contributors
author是一個(gè)人梳杏。contributors是一堆人的數(shù)組韧拒。person是一個(gè)有name字段，可選的有url十性、email字段的對象叛溢，像這樣：

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

或者可以把所有的東西都放到一個(gè)字符串里，npm會給你解析：
"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)

email和url在兩種形式中都是可選的劲适。
也可以在你的npm用戶信息中設(shè)置一個(gè)頂級的maintainers字段楷掉。

十二、files

files是一個(gè)包含項(xiàng)目中的文件的數(shù)組霞势。如果命名了一個(gè)文件夾烹植，那也會包含文件夾中的文件斑鸦。（除非被其他條件忽略了）
你也可以提供一個(gè).npmignore文件，讓即使被包含在files字段中得文件被留下草雕。其實(shí)就像.gitignore一樣鄙才。

image.png

十三、main

main字段配置一個(gè)文件名指向模塊的入口程序促绵。如果你包的名字叫foo，然后用戶require("foo")嘴纺，main配置的模塊的exports對象會被返回败晴。
這應(yīng)該是一個(gè)相對于根目錄的文件路徑。

十四栽渴、bin

很多包都有一個(gè)或多個(gè)可執(zhí)行的文件希望被放到PATH中尖坤。npm讓媽媽再也不用擔(dān)心了（實(shí)際上，就是這個(gè)功能讓npm可執(zhí)行的）闲擦。
要用這個(gè)功能慢味，給package.json中的bin
字段一個(gè)命令名到文件位置的map。初始化的時(shí)候npm會將他鏈接到prefix/bin
（全局初始化）或者./node_modules/.bin/
（本地初始化）墅冷。
比如纯路，npm有：

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

所以，當(dāng)你初始化npm寞忿，它會創(chuàng)建一個(gè)符號鏈接到cli.js
腳本到/usr/local/bin/npm驰唬。
如果你只有一個(gè)可執(zhí)行文件，并且名字和包名一樣腔彰。那么你可以只用一個(gè)字符串叫编，比如：

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

結(jié)果和這個(gè)一樣：

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

十五、man

指定一個(gè)單一的文件或者一個(gè)文件數(shù)組供man程序使用霹抛。
如果只提供一個(gè)單一的文件搓逾，那么它初始化后就是man <pkgname>
的結(jié)果，而不管實(shí)際的文件名是神馬杯拐，比如：

{ 
  "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創(chuàng)建文件寇损。
man文件需要以數(shù)字結(jié)束，然后可選地壓縮后以.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創(chuàng)建矛市。

directories

CommonJS Packages規(guī)范說明了幾種方式讓你可以用directories
hash標(biāo)示出包得結(jié)構(gòu)。如果看一下npm's package.json诲祸，你會看到有directories標(biāo)示出doc, lib, and man浊吏。
在未來而昨，這個(gè)信息可能會被用到。

directories.lib

告訴屌絲們你的庫文件夾在哪里找田。目前沒有什么特別的東西需要用到lib文件夾歌憨，但確實(shí)是重要的元信息。

directories.bin

如果你指定一個(gè)“bin”目錄墩衙，然后在那個(gè)文件夾中得所有文件都會被當(dāng)做"bin"字段使用务嫡。
如果你已經(jīng)指定了“bin”字段，那這個(gè)就無效漆改。

directories.man

一個(gè)放滿man頁面的文件夾心铃。貼心地創(chuàng)建一個(gè)“man”字段。A folder that is full of man pages. Sugar to generate a "man" array bywalking the folder.

directories.doc

將markdown文件放在這里挫剑。最后去扣，這些會被很好地展示出來，也許樊破，某一天愉棱。Put markdown files in here. Eventually, these will be displayed nicely,maybe, someday.

directories.example

將事例腳本放在這里。某一天哲戚，它可能會以聰明的方式展示出來奔滑。

repository

指定你的代碼存放的地方。這個(gè)對希望貢獻(xiàn)的人有幫助惫恼。如果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應(yīng)該是公開的（即便是只讀的）能直接被未經(jīng)過修改的版本控制程序處理的url祈纯。不應(yīng)該是一個(gè)html的項(xiàng)目頁面令宿。因?yàn)樗墙o計(jì)算機(jī)看的。

config

"config" hash可以用來配置用于包腳本中的跨版本參數(shù)腕窥。在實(shí)例中粒没，如果一個(gè)包有下面的配置：

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

然后有一個(gè)“start”命令引用了npm_package_config_port
環(huán)境變量，用戶可以通過npm config set foo:port 8001
來重寫他簇爆。
參見 npm-config(7) 和 npm-scripts(7)癞松。

engines

你可以指定工作的node的版本：

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

并且，像dependensies一樣入蛆，如果你不指定版本或者指定“*”作為版本响蓉，那么所有版本的node都可以。
如果指定一個(gè)“engines”字段哨毁，那么npm會需要node在里面枫甲，如果“engines”被省略，npm會假定它在node上工作。
你也可以用“engines”字段來指定哪一個(gè)npm版本能更好地初始化你的程序想幻，如：

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

記住粱栖，除非用戶設(shè)置engine-strict標(biāo)記，這個(gè)字段只是建議值脏毯。

• engineStrict

如果你確定你的模塊一定不會運(yùn)行在你指定版本之外的node或者npm上闹究，你可以在package.json文件中設(shè)置"engineStrict":true。它會重寫用戶的engine-strict
設(shè)置食店。
除非你非常非常確定渣淤，否則不要這樣做。如果你的engines hash過度地限制吉嫩，很可能輕易讓自己陷入窘境砂代。慎重地考慮這個(gè)選擇。如果大家濫用它率挣，它會再以后的npm版本中被刪除。

• os

你可以指定你的模塊要運(yùn)行在哪些操作系統(tǒng)中：
"os" : [ "darwin", "linux" ]

你也可以用黑名單代替白名單露戒，在名字前面加上“!”就可以了：
"os" : [ "!win32" ]

操作系統(tǒng)用process.platform來探測椒功。
雖然沒有很好地理由，但它是同時(shí)支持黑名單和白名單的智什。

• cpu

如果你的代碼只能運(yùn)行在特定的cpu架構(gòu)下动漾，你可以指定一個(gè)：
"cpu" : [ "x64", "ia32" ]

就像os選項(xiàng)，你也可以黑一個(gè)架構(gòu)：
"cpu" : [ "!arm", "!mips" ]

cpu架構(gòu)用process.arch探測荠锭。

• preferGlobal

如果包主要是需要全局安裝的命令行程序旱眯，就設(shè)置它為true
來提供一個(gè)warning給只在局部安裝的人。
它不會真正的防止用戶在局部安裝证九，但如果它沒有按預(yù)期工作它會幫助防止產(chǎn)生誤會删豺。

• private

如果你設(shè)置 "private": true，npm就不會發(fā)布它愧怜。
這是一個(gè)防止意外發(fā)布私有庫的方式呀页。如果你要確定給定的包是只發(fā)布在特定registry（如內(nèi)部registry）的，用publishConfig hash的描述來重寫registry的publish-time配置參數(shù)拥坛。

• publishConfig

這是一個(gè)在publish-time使用的配置集合蓬蝶。當(dāng)你想設(shè)置tag或者registry的時(shí)候它非常有用，所以你可以確定一個(gè)給定的包沒有打上“l(fā)astest”的tag或者被默認(rèn)發(fā)布到全局的公開registry猜惋。
任何配置都可以被重寫丸氛，但當(dāng)然可能只有“tag”和“registry”與發(fā)布的意圖有關(guān)。
參見npm-config(7)有可以被重寫的列表著摔。

• DEFAULT VALUES

npm會根據(jù)包的內(nèi)容設(shè)置一些默認(rèn)值缓窜。
"scripts": {"start": "node server.js"}

如果包的根目錄有server.js文件，npm會默認(rèn)將start命令設(shè)置為node server.js。

"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}

如果包的根目錄有wscript文件雹洗，npm會默認(rèn)將preinstall命令用node-waf進(jìn)行編譯香罐。

"scripts":{"preinstall": "node-gyp rebuild"} 

如果包的根目錄有binding.gyp文件，npm會默認(rèn)將preinstall命令用node-gyp進(jìn)行編譯时肿。

"contributors": [...]

如果有AUTHORS
文件庇茫，npm會默認(rèn)逐行按Name <email> (url)格式處理，郵箱和url是可選的螃成。#號和空格開頭的行會被忽略旦签。

SEE ALSO
semver(7)
npm-init(1)
npm-version(1)
npm-config(1)
npm-config(7)
npm-help(1)
npm-faq(7)
npm-install(1)
npm-publish(1)
npm-rm(1)