nodejs npm package.json中文文件_node.js

簡介

本文檔有所有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 (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" : "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 (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 的結果，而不管實際的文件名稱是神馬，例如：

複製程式碼 程式碼如下:

{ "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. 5. 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 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   , "baz" : ">1.0.2   , "boo" : "2.0.1"
  , "qux" : "=2.3.1 =2.5.2   , "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可能會產生下面的依賴關係

複製程式碼 程式碼如下:

├�� 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

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

而且，像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。

任何配置都可以被重寫，但當然可能只有「標籤」和「registry」與發布的意圖有關。

請參考npm-config(7)有可以重寫的清單。