本文整理 package.json 中所有重要欄位的用途。它必須是合法的 JSON,而不是 JS 物件;文中描述的許多行為還會受到 npm 設定檔影響。
npm 會依據套件內容套用一些預設值:
"scripts": { "start": "node server.js" }
若根目錄存在 server.js,start 指令預設即為上式。
"scripts": { "preinstall": "node-waf clean || true; node-waf configure build" }
若根目錄有 wscript 檔,preinstall 預設以 node-waf 編譯。
"scripts": { "preinstall": "node-gyp rebuild" }
若有 binding.gyp,則預設改用 node-gyp 編譯。
此外,若存在 AUTHORS 檔,npm 會逐行以 Name <email> (url) 格式解析為 contributors,以 # 或空白起始的行會被忽略。
這兩個是最重要的必填欄位,缺任何一個都無法安裝。name 與 version 組成的標識在 registry 中被視為唯一,因此改動套件內容時也必須更動版號。
關於命名,有幾點須注意:不要把 node 或 js 放進名稱(有 package.json 就已被預設為 JS 套件,若需指定執行環境請用 engines);名稱會成為 URL 的一部分、命令列參數與資料夾名,因此不能使用非 URL 安全字元;名稱會被傳入 require(),所以宜短而清晰;取名之前請先到 npm registry 確認是否已被占用。
version 必須能被 node-semver 解析,可用格式參考 semver 規範。
前者是字串簡介,後者是字串陣列,兩者都會被 npm search 用來比對,寫得清楚能大幅提高被找到的機會。
homepage 是專案官網網址。注意它與 url 不同:若填了 url 欄位,registry 會誤以為是跳轉到發布於他處的位址而予以拒絕。
bugs 用來指向問題回報管道,可同時提供網址與信箱:
{
"url": "https://github.com/owner/project/issues",
"email": "project@hostname.com"
}
若只需提供網址,直接寫成字串即可。有提供 url 時,npm bugs 指令會使用它。
應該明確標示授權條款。若採用 BSD、MIT 這類通用授權,只需寫名稱:
{ "license": "BSD" }
若條款較複雜或需補充細節:
"licenses": [
{ "type": "MyLicense",
"url": "https://github.com/owner/project/path/to/license" }
]
在根目錄放一份授權文件也是好習慣。
author 是一個人,contributors 是人物陣列。每個 person 物件需有 name,url 與 email 為選填:
{
"name": "Barney Rubble",
"email": "b@rubble.com",
"url": "https://barnyrubble.tumblr.com/"
}
也可以全部塞進一個字串,npm 會自行解析:
"Barney Rubble <b@rubble.com> (https://barnyrubble.tumblr.com/)"
files 是會被打進套件的檔案清單;指定資料夾時會包含其中的檔案(除非被其他規則排除)。也可用 .npmignore 排除特定檔案,用法與 .gitignore 相同。
main 是進入點的模組 ID,指向_relative_ 於根目錄的主要檔案。當使用者 require("foo") 時,得到的就是這個模組的 exports 物件。
許多套件會提供希望被放進 PATH 的可執行檔。在 bin 中定義「指令名 → 檔案路徑」的對應,npm 安裝時會建立符號連結:全域安裝連到 prefix/bin,區域安裝連到 ./node_modules/.bin/。
{ "bin": { "npm": "./cli.js" } }
若只有一個可執行檔且名稱與套件相同,可簡寫為字串:
{
"name": "my-program",
"version": "1.2.5",
"bin": "./path/to/program"
}
等效於 "bin": { "my-program": "./path/to/program" }。
指定單一檔案或陣列供 man 使用。若只給一個檔案,不論實際檔名為何,安裝後都以 man <pkgname> 存取:
{
"name": "foo",
"version": "1.2.3",
"main": "foo.js",
"man": "./man/doc.1"
}
若檔名不是以套件名開頭,會被冠上前綴:
{
"name": "foo",
"version": "1.2.3",
"main": "foo.js",
"man": [ "./man/foo.1", "./man/bar.1" ]
}
man 檔名須以數字結尾(可選 .gz 壓縮後綴),數字決定安裝到哪個 man 章節,例如 ./man/foo.2 對應 man 2 foo。
CommonJS 套件規範定義了以 directories 標示結構的方式。常見欄位包括:
lib:函式庫所在資料夾,目前雖無特殊用途,但屬重要中繼資訊。bin:指定後該資料夾內所有檔案都會被視為 bin;若已明確定義 bin 欄位則此項無效。man:放置 man 頁面的資料夾,等同自動產生 man 陣列。doc:放置 Markdown 文件。example:放置範例腳本。標明原始碼位置,方便他人參與貢獻。若 git repo 在 GitHub 上,npm docs 指令能直接找到它。
"repository":
{ "type": "git"
, "url": "https://github.com/isaacs/npm.git"
}
URL 應為公開可讀、能被版本控制工具直接處理的位址,而非 HTML 專案頁面——這個欄位是給程式讀的。
由指令組成的對應表,鍵為生命週期事件名稱,值為要執行的命令,例如 prepublish、preinstall、test 等。
用來設定供套件腳本使用的參數。例如:
{
"name": "foo",
"config": { "port": "8080" }
}
腳本中即可透過環境變數 npm_package_config_port 取得,而使用者可用 npm config set foo:port 8001 覆寫。
以「套件名 → 版本範圍」的對應表宣告執行期依賴,版本範圍也可以直接給 tarball 或 git URL。測試框架、文件工具等開發期才需要的項目請勿放在這裡,應歸入 devDependencies。
常見的版本表示法:
{
"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": "https://asdf.com/asdf.tar.gz",
"til": "~1.2",
"elf": "~1.2.3",
"two": "2.x",
"thr": "3.3.x"
}
}
依賴可以是 tarball URL(安裝時下載並解壓),也可以是 git URL:
git://github.com/user/project.git#commit-ish git+ssh://user@hostname:project.git#commit-ish git+https://user@hostname/project/blah.git#commit-ish git+https://user@hostname/project/blah.git#commit-ish
commit-ish 可以是任何 git checkout 能接受的 tag、sha 或 branch,預設為 master。此外也可簡寫成 user/foo-project 直接引用 GitHub。
當他人只想使用你的模組,通常不需要下載並建置你開發時用的測試或文件框架,因此這些附屬項目應獨立放在此欄。它們會在本機執行 npm link 或 npm install 時安裝。
對於與平台無關的建置步驟(例如把 CoffeeScript 編譯為 JavaScript),建議用 prepublish 腳本處理並把工具列進 devDependencies:
{
"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"
}
用於表達「與宿主套件的相容關係」,最常見的場景是外掛:你的模組會暴露特定介面,由宿主端決定實際版本。
{
"name": "tea-latte",
"version": "1.3.5",
"peerDependencies": {
"tea": "2.x"
}
}
這樣能確保 tea-latte 只與 tea 2.x 搭配安裝。若安裝了另一個要求衝突的外掛就會報錯。因此,外掛的版本約束應盡量寬鬆,不要鎖定到單一版本。若宿主遵循 semver,只有主版本變更才會破壞相容性,那麼用 ^1.0 或 1.x 表達即可;若依賴 1.5.2 才有的功能,則寫 >= 1.5.2 < 2。
前者是一組會隨發布一起打包的套件名,寫成 bundleDependencies 亦可。
後者則是「有則更好、沒有也能運作」的依賴,格式與 dependencies 相同,但安裝失敗時 npm 不會中斷流程:
try {
var foo = require('foo');
var fooVersion = require('foo/package.json').version;
} catch (er) {
foo = null;
}
if (notGoodFooVersion(fooVersion)) {
foo = null;
}
// ... 後續使用時再判斷
if (foo) {
foo.doFooThings();
}
optionalDependencies 會覆蓋 dependencies 中的同名項,因此同一套件通常只放在一處。
{ "engines": { "node": ">=0.10.3 <0.12" } }
省略或填 * 代表不限版本。也可用它標示適用的 npm 版本:
{ "engines": { "npm": "~1.0.20" } }
除非使用者開啟 engine-strict,這個欄位僅為建議。若確定模組無法在指定版本外運行,可設 "engineStrict": true 覆寫使用者設定——但請審慎為之,過度嚴格的 engines 很容易讓自己陷入困境,若被濫用,這個選項可能在後續 npm 版本中被移除。
可限制適用的作業系統,同時支援白名單與黑名單(在前面加 !):
"os": [ "darwin", "linux" ] "os": [ "!win32" ]
作業系統由 process.platform 判斷。CPU 架構同理,由 process.arch 判斷:
"cpu": [ "x64", "ia32" ] "cpu": [ "!arm", "!mips" ]
preferGlobal 設為 true 時,若使用者以區域安裝方式裝了主要供命令列使用的套件,npm 會給出警告。它不會阻止安裝,但能避免誤解。
"private": true 可防止套件被誤發布。若需要發布到特定 registry(如內部 registry),請改用 publishConfig 覆寫發布時的設定。
publishConfig 是一組僅在發布時生效的設定,常用於指定 tag 或 registry,確保套件不會被打上 latest 標籤或誤傳至公開 registry。任何設定都可被覆寫,但實際上與發布意圖相關的主要就是 tag 與 registry 兩項。