DIV CSS 佈局教程網

npm package.json 欄位完整中文說明
編輯:關於JavaScript     

本文整理 package.json 中所有重要欄位的用途。它必須是合法的 JSON,而不是 JS 物件;文中描述的許多行為還會受到 npm 設定檔影響。

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

這兩個是最重要的必填欄位,缺任何一個都無法安裝。name 與 version 組成的標識在 registry 中被視為唯一,因此改動套件內容時也必須更動版號。

關於命名,有幾點須注意:不要把 node 或 js 放進名稱(有 package.json 就已被預設為 JS 套件,若需指定執行環境請用 engines);名稱會成為 URL 的一部分、命令列參數與資料夾名,因此不能使用非 URL 安全字元;名稱會被傳入 require(),所以宜短而清晰;取名之前請先到 npm registry 確認是否已被占用。

version 必須能被 node-semver 解析,可用格式參考 semver 規範。

description 與 keywords

前者是字串簡介,後者是字串陣列,兩者都會被 npm search 用來比對,寫得清楚能大幅提高被找到的機會。

homepage、bugs 與 license

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

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 與 main

files 是會被打進套件的檔案清單;指定資料夾時會包含其中的檔案(除非被其他規則排除)。也可用 .npmignore 排除特定檔案,用法與 .gitignore 相同。

main 是進入點的模組 ID,指向_relative_ 於根目錄的主要檔案。當使用者 require("foo") 時,得到的就是這個模組的 exports 物件。

bin

許多套件會提供希望被放進 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 使用。若只給一個檔案,不論實際檔名為何,安裝後都以 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。

directories

CommonJS 套件規範定義了以 directories 標示結構的方式。常見欄位包括:

  • lib:函式庫所在資料夾,目前雖無特殊用途,但屬重要中繼資訊。
  • bin:指定後該資料夾內所有檔案都會被視為 bin;若已明確定義 bin 欄位則此項無效。
  • man:放置 man 頁面的資料夾,等同自動產生 man 陣列。
  • doc:放置 Markdown 文件。
  • example:放置範例腳本。

repository

標明原始碼位置,方便他人參與貢獻。若 git repo 在 GitHub 上,npm docs 指令能直接找到它。

"repository":
  { "type": "git"
  , "url": "https://github.com/isaacs/npm.git"
  }

URL 應為公開可讀、能被版本控制工具直接處理的位址,而非 HTML 專案頁面——這個欄位是給程式讀的。

scripts

由指令組成的對應表,鍵為生命週期事件名稱,值為要執行的命令,例如 prepublish、preinstall、test 等。

config

用來設定供套件腳本使用的參數。例如:

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

腳本中即可透過環境變數 npm_package_config_port 取得,而使用者可用 npm config set foo:port 8001 覆寫。

dependencies

以「套件名 → 版本範圍」的對應表宣告執行期依賴,版本範圍也可以直接給 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。

devDependencies

當他人只想使用你的模組,通常不需要下載並建置你開發時用的測試或文件框架,因此這些附屬項目應獨立放在此欄。它們會在本機執行 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"
}

peerDependencies

用於表達「與宿主套件的相容關係」,最常見的場景是外掛:你的模組會暴露特定介面,由宿主端決定實際版本。

{
  "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。

bundledDependencies 與 optionalDependencies

前者是一組會隨發布一起打包的套件名,寫成 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 與 engineStrict

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

省略或填 * 代表不限版本。也可用它標示適用的 npm 版本:

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

除非使用者開啟 engine-strict,這個欄位僅為建議。若確定模組無法在指定版本外運行,可設 "engineStrict": true 覆寫使用者設定——但請審慎為之,過度嚴格的 engines 很容易讓自己陷入困境,若被濫用,這個選項可能在後續 npm 版本中被移除。

os 與 cpu

可限制適用的作業系統,同時支援白名單與黑名單(在前面加 !):

"os": [ "darwin", "linux" ]
"os": [ "!win32" ]

作業系統由 process.platform 判斷。CPU 架構同理,由 process.arch 判斷:

"cpu": [ "x64", "ia32" ]
"cpu": [ "!arm", "!mips" ]

preferGlobal、private 與 publishConfig

preferGlobal 設為 true 時,若使用者以區域安裝方式裝了主要供命令列使用的套件,npm 會給出警告。它不會阻止安裝,但能避免誤解。

"private": true 可防止套件被誤發布。若需要發布到特定 registry(如內部 registry),請改用 publishConfig 覆寫發布時的設定。

publishConfig 是一組僅在發布時生效的設定,常用於指定 tag 或 registry,確保套件不會被打上 latest 標籤或誤傳至公開 registry。任何設定都可被覆寫,但實際上與發布意圖相關的主要就是 tag 與 registry 兩項。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved