npm package.json屬性詳解

桃子夭夭發表於2016-02-16
NPMPackageJSON

概述

本文件是自己看官方文件的理解+翻譯，內容是package.json配置裡邊的屬性含義。package.json必須是一個嚴格的json檔案，而不僅僅是js裡邊的一個物件。其中很多屬性可以通過npm-config來生成。

name

package.json中最重要的屬性是name和version兩個屬性，這兩個屬性是必須要有的，否則模組就無法被安裝，這兩個屬性一起形成了一個npm模組的唯一識別符號。模組中內容變更的同時，模組版本也應該一起變化。
name屬性就是你的模組名稱，下面是一些命名規則:

  • name必須小於等於214個位元組，包括字首名稱在內（如 xxx/xxxmodule）。
  • name不能以"_"或"."開頭
  • 不能含有大寫字母
  • name會成為url的一部分，不能含有url非法字元
    下面是官網文件的一些建議：
  • 不要使用和node核心模組一樣的名稱
  • name中不要含有"js"和"node"。 It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)
  • name屬性會成為模組url、命令列中的一個引數或者一個資料夾名稱，任何非url安全的字元在name中都不能使用，也不能以"_"或"."開頭
  • name屬性也許會被寫在require()的引數中，所以最好取個簡短而語義化的值。
  • 建立一個模組前可以先到後邊的網址查查name是否已經被佔用. https://www.npmjs.com/

name屬性可以有一些字首如 e.g. @myorg/mypackage.在npm-scope(7)的文件中可以看到詳細說明

version

version必須可以被npm依賴的一個node-semver模組解析。具體規則見下面的dependencies模組

description

一個描述，方便別人瞭解你的模組作用，搜尋的時候也有用。

keywords

一個字串陣列，方便別人搜尋到本模組

homepage

專案主頁url
注意: 這個專案主頁url和url屬性不同，如果你填寫了url屬性，npm註冊工具會認為你把專案釋出到其他地方了，獲取模組的時候不會從npm官方倉庫獲取，而是會重定向到url屬性配置的地址。
（原文件中用了 spit(吐)這個單詞，作者表示他不是在開玩笑:）

bugs

填寫一個bug提交地址或者一個郵箱，被你的模組坑到的人可以通過這裡吐槽，例如：

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

url和email可以任意填或不填，如果只填一個，可以直接寫成一個字串而不是物件。如果填寫了url，npm bugs命令會使用這個url。

license

你應該為你的模組制定一個協議，讓使用者知道他們有何許可權來使用你的模組，以及使用該模組有哪些限制。最簡單的，例如你用BSD-3-Clause 或 MIT之類的協議，如下：
{ "license" : "BSD-3-Clause" }
你可以在https://spdx.org/licenses/這個地址查閱協議列表 。

和使用者相關的屬性: author, contributors

"author"是一個碼農， "contributors"是一個碼農陣列。 "person"是一個有一些描述屬性的物件，如下 like this:

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

也可以按如下格式縮寫，npm會幫著轉換:
"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)"
email和url屬性實際上都是可以省略的。描述使用者資訊的還有一個"maintainers"（維護者）屬性。

files

"files"屬性的值是一個陣列，內容是模組下檔名或者資料夾名，如果是資料夾名，則資料夾下所有的檔案也會被包含進來（除非檔案被另一些配置排除了）
你也可以在模組根目錄下建立一個".npmignore"檔案（windows下無法直接建立以"."開頭的檔案，使用linux命令列工具建立如git bash），寫在這個檔案裡邊的檔案即便被寫在files屬性裡邊也會被排除在外，這個檔案的寫法".gitignore"類似。

main

main屬性指定了程式的主入口檔案。意思是，如果你的模組被命名為foo，使用者安裝了這個模組並通過require("foo")來使用這個模組，那麼require返回的內容就是main屬性指定的檔案中 module.exports指向的物件。
它應該指向模組根目錄下的一個檔案。對大對數模組而言，這個屬性更多的是讓模組有一個主入口檔案，然而很多模組並不寫這個屬性。

bin

很多模組有一個或多個需要配置到PATH路徑下的可執行模組，npm讓這個工作變得十分簡單（實際上npm本身也是通過bin屬性安裝為一個可執行命令的）
如果要用npm的這個功能，在package.json裡邊配置一個bin屬性。bin屬性是一個已命令名稱為key，本地檔名稱為value的map如下：

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

模組安裝的時候，若是全域性安裝，則npm會為bin中配置的檔案在bin目錄下建立一個軟連線（對於windows系統，預設會在C:\Users\username\AppData\Roaming\npm目錄下），若是區域性安裝，則會在專案內的./node_modules/.bin/目錄下建立一個軟連結。
因此，按上面的例子，當你安裝myapp的時候，npm就會為cli.js在/usr/local/bin/myapp路徑建立一個軟連結。
如果你的模組只有一個可執行檔案，並且它的命令名稱和模組名稱一樣，你可以只寫一個字串來代替上面那種配置，例如：

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

制定一個或通過陣列制定一些檔案來讓linux下的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 檔案的內容。
如果man檔名稱不是以模組名稱開頭的，安裝的時候會給加上模組名稱字首。因此，下面這段配置：

{ "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結尾。數字表示檔案將被安裝到man的哪個部分。

{ "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通過directories來制定一些方法來描述模組的結構，看看npm的package.json檔案https://registry.npmjs.org/npm/latest ，可以發現裡邊有這個欄位的內容。
npm package.json屬性詳解
目前這個配置沒有任何作用，將來可能會整出一些花樣來。

directories.lib

告訴使用者模組中lib目錄在哪，這個配置目前沒有任何作用，但是對使用模組的人來說是一個很有用的資訊。

directories.bin

如果你在這裡指定了bin目錄，這個配置下面的檔案會被加入到bin路徑下，如果你已經在package.json中配置了bin目錄，那麼這裡的配置將不起任何作用。

directories.man

指定一個目錄，目錄裡邊都是man檔案，這是一種配置man檔案的語法糖。

directories.doc

在這個目錄裡邊放一些markdown檔案，可能最終有一天它們會被友好的展現出來（應該是在npm的網站上）

directories.example

放一些示例指令碼，或許某一天會有用 - -！

repository

指定一個程式碼存放地址，對想要為你的專案貢獻程式碼的人有幫助。像這樣：

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

"repository" :
  { "type" : "svn"
  , "url" : "https://v8.googlecode.com/svn/trunk/"
  }

若你的模組放在GitHub, GitHub gist, Bitbucket, or GitLab的倉庫裡，npm install的時候可以使用縮寫標記來完成：

"repository": "npm/npm"

"repository": "gist:11081aaa281"

"repository": "bitbucket:example/repo"

"repository": "gitlab:another/repo"

scripts

scripts屬性是一個物件，裡邊指定了專案的生命週期個各個環節需要執行的命令。key是生命週期中的事件，value是要執行的命令。
具體的內容有 install start stop 等，詳見https://docs.npmjs.com/misc/scripts

config

用來設定一些專案不怎麼變化的專案配置，例如port等。
使用者用的時候可以使用如下用法：

http.createServer(...).listen(process.env.npm_package_config_port)

可以通過npm config set foo:port 80來修改config。詳見https://docs.npmjs.com/misc/config

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

dependencies

dependencies屬性是一個物件，配置模組依賴的模組列表，key是模組名稱，value是版本範圍，版本範圍是一個字元，可以被一個或多個空格分割。
dependencies也可以被指定為一個git地址或者一個壓縮包地址。
不要把測試工具或transpilers寫到dependencies中。 下面是一些寫法，詳見https://docs.npmjs.com/misc/semver

  • version 精確匹配版本
  • >version 必須大於某個版本
  • >=version 大於等於
  • <version 小於
  • <=versionversion 小於
  • ~version "約等於"，具體規則詳見semver文件
  • ^version "相容版本"具體規則詳見semver文件
  • 1.2.x 僅一點二點幾的版本
  • http://... 見下面url作為denpendencies的說明
    • 任何版本
  • "" 空字元，和*相同
  • version1 - version2 相當於 >=version1 <=version2.
  • range1 || range2 範圍1和範圍2滿足任意一個都行
  • git... 見下面git url作為denpendencies的說明
  • user/repo See 見下面GitHub倉庫的說明
  • tag 釋出的一個特殊的標籤，見npm-tag的文件 https://docs.npmjs.com/getting-started/using-tags
  • path/path/path 見下面本地模組的說明
    下面的寫法都是可以的:
{ "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"
  , "lat" : "latest"
  , "dyl" : "file:../dyl"
  }
}

URLs as Dependencies

在版本範圍的地方可以寫一個url指向一個壓縮包，模組安裝的時候會把這個壓縮包下載下來安裝到模組本地。

Git URLs as Dependencies

Git url可以像下面一樣:

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 可以是任意標籤，雜湊值，或者可以檢出的分支，預設是master分支。

GitHub URLs

支援github的 username/modulename 的寫法，#後邊可以加字尾寫明分支hash或標籤：

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

Local Paths

npm2.0.0版本以上可以提供一個本地路徑來安裝一個本地的模組，通過npm install xxx --save 來安裝，格式如下：

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

package.json 生成的相對路徑如下:

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

這種屬性在離線開發或者測試需要用npm install的情況，又不想自己搞一個npm server的時候有用，但是釋出模組到公共倉庫時不應該使用這種屬性。

devDependencies

如果有人想要下載並使用你的模組，也許他們並不希望或需要下載一些你在開發過程中使用的額外的測試或者文件框架。
在這種情況下，最好的方法是把這些依賴新增到devDependencies屬性的物件中。
這些模組會在npm link或者npm install的時候被安裝，也可以像其他npm配置一樣被管理，詳見npm的config文件。
對於一些跨平臺的構建任務，例如把CoffeeScript編譯成JavaScript，就可以通過在package.json的script屬性裡邊配置prepublish指令碼來完成這個任務，然後需要依賴的coffee-script模組就寫在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"
}

prepublish指令碼會在釋出之前執行，因此使用者在使用之前就不用再自己去完成編譯的過程了。在開發模式下，執行npm install也會執行這個指令碼（見npm script文件），因此可以很方便的除錯。

peerDependencies

有時候做一些外掛開發，比如grunt等工具的外掛，它們往往是在grunt的某個版本的基礎上開發的，而在他們的程式碼中並不會出現require("grunt")這樣的依賴，dependencies配置裡邊也不會寫上grunt的依賴，為了說明此模組只能作為外掛跑在宿主的某個版本範圍下，可以配置peerDependencies：

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

上面這個配置確保再npm install的時候tea-latte會和2.x版本的tea一起安裝，而且它們兩個的依賴關係是同級的：
├── tea-latte@1.3.5
└── tea@2.2.0
這個配置的目的是讓npm知道，如果要使用此外掛模組，請確保安裝了相容版本的宿主模組。

bundledDependencies

上面的單詞少個d，寫成bundleDependencies也可以。
指定釋出的時候會被一起打包的模組。

optionalDependencies

如果一個依賴模組可以被使用， 同時你也希望在該模組找不到或無法獲取時npm繼續執行，你可以把這個模組依賴放到optionalDependencies配置中。這個配置的寫法和dependencies的寫法一樣，不同的是這裡邊寫的模組安裝失敗不會導致npm install失敗。
當然，這種模組就需要你自己在程式碼中處理模組確實的情況了，例如：

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" } }
和dependencies一樣，如果你不指定版本範圍或者指定為*，任何版本的node都可以。
也可以指定一些npm版本可以正確的安裝你的模組，例如：
{ "engines" : { "npm" : "~1.0.20" } }
要注意的是，除非你設定了engine-strict屬性，engines屬性是僅供參考的。

engineStrict

注意：這個屬性已經棄用，將在npm 3.0.0 版本幹掉。

os

可以指定你的模組只能在哪個作業系統上跑：
"os" : [ "darwin", "linux" ]
也可以指定黑名單而不是白名單：
"os" : [ "!win32" ]
服務的作業系統是由process.platform來判斷的，這個屬性允許黑白名單同時存在，雖然沒啥必要這樣搞...

cpu

限制模組只能在某某cpu架構下執行
"cpu" : [ "x64", "ia32" ]
同樣可以設定黑名單:
"cpu" : [ "!arm", "!mips" ]
cpu架構通過 process.arch 判斷

preferGlobal

如果您的軟體包主要用於安裝到全域性的命令列應用程式，那麼該值設定為true ，如果它被安裝在本地，則提供一個警告。實際上該配置並沒有阻止使用者把模組安裝到本地，只是防止該模組被錯誤的使用引起一些問題。

private

如果這個屬性被設定為true，npm將拒絕釋出它，這是為了防止一個私有模組被無意間釋出出去。如果你只想讓模組被髮布到一個特定的npm倉庫，如一個內部的倉庫，可與在下面的publishConfig中配置倉庫引數。

publishConfig

這個配置是會在模組釋出時用到的一些值的集合。如果你不想模組被預設被標記為最新的，或者預設釋出到公共倉庫，可以在這裡配置tag或倉庫地址。

DEFAULT VALUES

npm設定了一些預設引數，如：
"scripts": {"start": "node server.js"}
如果模組根目錄下有一個server.js檔案，那麼npm start會預設執行這個檔案。
"scripts":{"preinstall": "node-gyp rebuild"}
如果模組根目錄下有binding.gyp, npm將預設用node-gyp來編譯preinstall的指令碼
"contributors": [...]
若模組根目錄下有AUTHORS 檔案，則npm會按Name (url)格式解析每一行的資料新增到contributors中，可以用#新增行註釋

參考文件列表(https://docs.npmjs.com/)

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)

轉自我的個人部落格，原文地址：http://zoucz.com/blog/2016/02/17/npm-package

相關文章