npm package.json字段全解

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）

description

Put a description in it. It's a string. This helps people discover your package, as it's listed in 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字段是一個模塊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是要運行的命令。

config

"config" hash能夠用來配置用於包腳本中的跨版本參數。在實例中，若是一個包有下面的配置：

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

而後有一個「start」命令引用了npm_package_config_port環境變量，用戶能夠經過npm config set foo:port 8001來重寫他。

dependencies

依賴是給一組包名指定版本範圍的一個hash。這個版本範圍是一個由一個或多個空格分隔的字符串。依賴還能夠用tarball或者git URL。

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

• version 必須徹底和version一致
• >version 必須比version大
• >=version 同上
• <version 同上
• <=version 同上
• ~version 約等於
• 1.2.x 1.2.0, 1.2.1, 等，但不包括1.3.0
• http://... 見下文'依賴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配置參數同樣管理。

對於非特定平臺的構建步驟，好比須要編譯CoffeeScript，能夠用prepublish腳本去實現，並把它依賴的包放在devDependency中。（譯者注：prepublish定義了在執行npm publish的時候先行執行的腳本。詳見scripts）

好比：

{ "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」與發佈的意圖有關。

DEFAULT VALUES

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是可選的。#號和空格開頭的行會被忽略。

參考網址1：http://www.mujiang.info/translation/npmjs/files/package.json.html

參考網址2：http://www.nopcn.com/post/npmjs-packagejson.aspx