概述

package.json必須是一個(gè)嚴(yán)格的json文件，而不僅僅是js里邊的一個(gè)對(duì)象。其中很多屬性可以通過(guò)npm-config來(lái)生成

name

package.json中最重要的屬性是name和version兩個(gè)屬性，這兩個(gè)屬性是必須要有的，否則模塊就無(wú)法被安裝，這兩個(gè)屬性一起形成了一個(gè)npm模塊的唯一標(biāo)識(shí)符。模塊中內(nèi)容變更的同時(shí)，模塊版本也應(yīng)該一起變化。 name屬性就是你的模塊名稱(chēng)，下面是一些命名規(guī)則:

• name必須小于等于214個(gè)字節(jié)，包括前綴名稱(chēng)在內(nèi)（如 xxx/xxxmodule）。

• name不能以"_"或"."開(kāi)頭

• 不能含有大寫(xiě)字母

• name會(huì)成為url的一部分，不能含有url非法字符

  下面是官網(wǎng)文檔的一些建議：

• 不要使用和node核心模塊一樣的名稱(chēng)

• 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屬性會(huì)成為模塊url、命令行中的一個(gè)參數(shù)或者一個(gè)文件夾名稱(chēng)，任何非url安全的字符在name中都不能使用，也不能以"_"或"."開(kāi)頭

• name屬性也許會(huì)被寫(xiě)在require()的參數(shù)中，所以最好取個(gè)簡(jiǎn)短而語(yǔ)義化的值。

• 創(chuàng)建一個(gè)模塊前可以先到后邊的網(wǎng)址查查name是否已經(jīng)被占用. www.npmjs.com/

  • # 發(fā)布一個(gè)包的時(shí)候，需要檢驗(yàn)?zāi)硞€(gè)包名是否存在
    npm search <ModuleName>

name屬性可以有一些前綴如 e.g. @myorg/mypackage.在npm-scope(7)的文檔中可以看到詳細(xì)說(shuō)明

version

version必須可以被npm依賴(lài)的一個(gè)node-semver模塊解析。具體規(guī)則見(jiàn)下面的dependencies模塊

description

一個(gè)描述，方便別人了解你的模塊作用，搜索的時(shí)候也有用。

keywords

一個(gè)字符串?dāng)?shù)組，方便別人搜索到本模塊

homepage

項(xiàng)目主頁(yè)url 注意: 這個(gè)項(xiàng)目主頁(yè)url和url屬性不同，如果你填寫(xiě)了url屬性，npm注冊(cè)工具會(huì)認(rèn)為你把項(xiàng)目發(fā)布到其他地方了，獲取模塊的時(shí)候不會(huì)從npm官方倉(cāng)庫(kù)獲取，而是會(huì)重定向到url屬性配置的地址。 （原文檔中用了 spit(吐)這個(gè)單詞，作者表示他不是在開(kāi)玩笑:）

bugs

填寫(xiě)一個(gè)bug提交地址或者一個(gè)郵箱，被你的模塊坑到的人可以通過(guò)這里吐槽，例如：

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

url和email可以任意填或不填，如果只填一個(gè)，可以直接寫(xiě)成一個(gè)字符串而不是對(duì)象。如果填寫(xiě)了url，npm bugs命令會(huì)使用這個(gè)url。

license

你應(yīng)該為你的模塊制定一個(gè)協(xié)議，讓用戶(hù)知道他們有何權(quán)限來(lái)使用你的模塊，以及使用該模塊有哪些限制。最簡(jiǎn)單的，例如你用BSD-3-Clause 或 MIT之類(lèi)的協(xié)議，如下：

{ "license" : "MIT" }

你可以在spdx.org/licenses/ 這個(gè)地址查閱協(xié)議列表 。

和用戶(hù)相關(guān)的屬性: author, contributors

author是一個(gè)碼農(nóng)， contributors是一個(gè)碼農(nóng)數(shù)組。 person是一個(gè)有一些描述屬性的對(duì)象，如下 like this:

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

也可以按如下格式縮寫(xiě)，npm會(huì)幫著轉(zhuǎn)換:

"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)"

email和url屬性實(shí)際上都是可以省略的。描述用戶(hù)信息的還有一個(gè)maintainers（維護(hù)者）屬性。

files

files屬性的值是一個(gè)數(shù)組，內(nèi)容是模塊下文件名或者文件夾名，如果是文件夾名，則文件夾下所有的文件也會(huì)被包含進(jìn)來(lái)（除非文件被另一些配置排除了） 你也可以在模塊根目錄下創(chuàng)建一個(gè).npmignore文件（windows下無(wú)法直接創(chuàng)建以"."開(kāi)頭的文件，使用linux命令行工具創(chuàng)建如git bash），寫(xiě)在這個(gè)文件里邊的文件即便被寫(xiě)在files屬性里邊也會(huì)被排除在外，這個(gè)文件的寫(xiě)法".gitignore"類(lèi)似。

main

main屬性指定了程序的主入口文件。意思是，如果你的模塊被命名為foo，用戶(hù)安裝了這個(gè)模塊并通過(guò)require("foo")來(lái)使用這個(gè)模塊，那么require返回的內(nèi)容就是main屬性指定的文件中 module.exports指向的對(duì)象。 它應(yīng)該指向模塊根目錄下的一個(gè)文件。對(duì)大對(duì)數(shù)模塊而言，這個(gè)屬性更多的是讓模塊有一個(gè)主入口文件，然而很多模塊并不寫(xiě)這個(gè)屬性。

bin

很多模塊有一個(gè)或多個(gè)需要配置到PATH路徑下的可執(zhí)行模塊，npm讓這個(gè)工作變得十分簡(jiǎn)單（實(shí)際上npm本身也是通過(guò)bin屬性安裝為一個(gè)可執(zhí)行命令的） 如果要用npm的這個(gè)功能，在package.json里邊配置一個(gè)bin屬性。bin屬性是一個(gè)已命令名稱(chēng)為key，本地文件名稱(chēng)為value的map如下：

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

模塊安裝的時(shí)候，若是全局安裝，則npm會(huì)為bin中配置的文件在bin目錄下創(chuàng)建一個(gè)軟連接（對(duì)于windows系統(tǒng)，默認(rèn)會(huì)在C:\Users\username\AppData\Roaming\npm目錄下），若是局部安裝，則會(huì)在項(xiàng)目?jī)?nèi)的./node_modules/.bin/目錄下創(chuàng)建一個(gè)軟鏈接。 因此，按上面的例子，當(dāng)你安裝myapp的時(shí)候，npm就會(huì)為cli.js在/usr/local/bin/myapp路徑創(chuàng)建一個(gè)軟鏈接。 如果你的模塊只有一個(gè)可執(zhí)行文件，并且它的命令名稱(chēng)和模塊名稱(chēng)一樣，你可以只寫(xiě)一個(gè)字符串來(lái)代替上面那種配置，例如：

{ 
    "name": "my-program",
    "version": "1.2.5", 
    "bin": "./path/to/program"
}

作用和如下寫(xiě)法相同:

{ 
    "name": "my-program", 
    "version": "1.2.5", 
    "bin" : { 
        "my-program" : "./path/to/program" 
    }
}

man

制定一個(gè)或通過(guò)數(shù)組制定一些文件來(lái)讓linux下的man命令查找文檔地址。 如果只有一個(gè)文件被指定的話(huà)，安裝后直接使用man+模塊名稱(chēng)，而不管man指定的文件的實(shí)際名稱(chēng)。例如:

{
    "name" : "foo",
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : "./man/doc.1"
}

通過(guò)man foo命令會(huì)得到 ./man/doc.1 文件的內(nèi)容。 如果man文件名稱(chēng)不是以模塊名稱(chēng)開(kāi)頭的，安裝的時(shí)候會(huì)給加上模塊名稱(chēng)前綴。因此，下面這段配置：

{ 
    "name" : "foo", 
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : [ "./man/foo.1", "./man/bar.1" ]
}

會(huì)創(chuàng)建一些文件來(lái)作為man foo和man foo-bar命令的結(jié)果。 man文件必須以數(shù)字結(jié)尾，或者如果被壓縮了，以.gz結(jié)尾。數(shù)字表示文件將被安裝到man的哪個(gè)部分。

{ 
    "name" : "foo", 
    "version" : "1.2.3",
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : [ "./man/foo.1", "./man/foo.2" ]
}

會(huì)創(chuàng)建 man foo 和 man 2 foo 兩條命令。

directories

CommonJs通過(guò)directories來(lái)制定一些方法來(lái)描述模塊的結(jié)構(gòu)，看看npm的package.json文件registry.npmjs.org/npm/latest 。

directories.lib

告訴用戶(hù)模塊中l(wèi)ib目錄在哪，這個(gè)配置目前沒(méi)有任何作用，但是對(duì)使用模塊的人來(lái)說(shuō)是一個(gè)很有用的信息。

directories.bin

如果你在這里指定了bin目錄，這個(gè)配置下面的文件會(huì)被加入到bin路徑下，如果你已經(jīng)在package.json中配置了bin目錄，那么這里的配置將不起任何作用。

directories.man

指定一個(gè)目錄，目錄里邊都是man文件，這是一種配置man文件的語(yǔ)法糖。

directories.doc

在這個(gè)目錄里邊放一些markdown文件，可能最終有一天它們會(huì)被友好的展現(xiàn)出來(lái)（應(yīng)該是在npm的網(wǎng)站上）

directories.example

放一些示例腳本，或許某一天會(huì)有用 - -！

repository

指定一個(gè)代碼存放地址，對(duì)想要為你的項(xiàng)目貢獻(xiàn)代碼的人有幫助。像這樣：

"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的倉(cāng)庫(kù)里，npm install的時(shí)候可以使用縮寫(xiě)標(biāo)記來(lái)完成：

"repository": "npm/npm"
"repository": "gist:11081aaa281"
"repository": "bitbucket:example/repo"
"repository": "gitlab:another/repo"

scripts

scripts屬性是一個(gè)對(duì)象，里邊指定了項(xiàng)目的生命周期個(gè)各個(gè)環(huán)節(jié)需要執(zhí)行的命令。key是生命周期中的事件，value是要執(zhí)行的命令。 具體的內(nèi)容有 install start stop 等，詳見(jiàn) https://docs.npmjs.com/misc/scripts

config

用來(lái)設(shè)置一些項(xiàng)目不怎么變化的項(xiàng)目配置，例如port等。 用戶(hù)用的時(shí)候可以使用如下用法：

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

可以通過(guò)npm config set foo:port 80來(lái)修改config。詳見(jiàn)docs.npmjs.com/misc/config

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

dependencies

dependencies屬性是一個(gè)對(duì)象，配置模塊依賴(lài)的模塊列表，key是模塊名稱(chēng)，value是版本范圍，版本范圍是一個(gè)字符，可以被一個(gè)或多個(gè)空格分割。 dependencies也可以被指定為一個(gè)git地址或者一個(gè)壓縮包地址。 不要把測(cè)試工具或transpilers寫(xiě)到dependencies中。 下面是一些寫(xiě)法，詳見(jiàn)docs.npmjs.com/misc/semver

• version 精確匹配版本
• >version 必須大于某個(gè)版本
• >=version 大于等于
• <version 小于
• <=versionversion 小于
• ~version "約等于"，具體規(guī)則詳見(jiàn)semver文檔
• ^version "兼容版本"具體規(guī)則詳見(jiàn)semver文檔
• 1.2.x 僅一點(diǎn)二點(diǎn)幾的版本
• http://... 見(jiàn)下面url作為denpendencies的說(shuō)明
• • 任何版本
• "" 空字符，和*相同
• version1 - version2 相當(dāng)于 >=version1 <=version2.
• range1 || range2 范圍1和范圍2滿(mǎn)足任意一個(gè)都行
• git... 見(jiàn)下面git url作為denpendencies的說(shuō)明
• user/repo See 見(jiàn)下面GitHub倉(cāng)庫(kù)的說(shuō)明
• tag 發(fā)布的一個(gè)特殊的標(biāo)簽，見(jiàn)npm-tag的文檔 docs.npmjs.com/getting-sta…
• path/path/path 見(jiàn)下面本地模塊的說(shuō)明 下面的寫(xiě)法都是可以的:

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

在版本范圍的地方可以寫(xiě)一個(gè)url指向一個(gè)壓縮包，模塊安裝的時(shí)候會(huì)把這個(gè)壓縮包下載下來(lái)安裝到模塊本地。

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 可以是任意標(biāo)簽，哈希值，或者可以檢出的分支，默認(rèn)是master分支。

GitHub URLs

支持github的 username/modulename 的寫(xiě)法，#后邊可以加后綴寫(xiě)明分支hash或標(biāo)簽：

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

Local Paths

npm2.0.0版本以上可以提供一個(gè)本地路徑來(lái)安裝一個(gè)本地的模塊，通過(guò)npm install xxx --save 來(lái)安裝，格式如下：

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

package.json 生成的相對(duì)路徑如下:

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

這種屬性在離線(xiàn)開(kāi)發(fā)或者測(cè)試需要用npm install的情況，又不想自己搞一個(gè)npm server的時(shí)候有用，但是發(fā)布模塊到公共倉(cāng)庫(kù)時(shí)不應(yīng)該使用這種屬性。

devDependencies

如果有人想要下載并使用你的模塊，也許他們并不希望或需要下載一些你在開(kāi)發(fā)過(guò)程中使用的額外的測(cè)試或者文檔框架。 在這種情況下，最好的方法是把這些依賴(lài)添加到devDependencies屬性的對(duì)象中。 這些模塊會(huì)在npm link或者npm install的時(shí)候被安裝，也可以像其他npm配置一樣被管理，詳見(jiàn)npm的config文檔。 對(duì)于一些跨平臺(tái)的構(gòu)建任務(wù)，例如把CoffeeScript編譯成JavaScript，就可以通過(guò)在package.json的script屬性里邊配置prepublish腳本來(lái)完成這個(gè)任務(wù)，然后需要依賴(lài)的coffee-script模塊就寫(xiě)在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腳本會(huì)在發(fā)布之前運(yùn)行，因此用戶(hù)在使用之前就不用再自己去完成編譯的過(guò)程了。在開(kāi)發(fā)模式下，運(yùn)行npm install也會(huì)執(zhí)行這個(gè)腳本（見(jiàn)npm script文檔），因此可以很方便的調(diào)試。

peerDependencies

有時(shí)候做一些插件開(kāi)發(fā)，比如grunt等工具的插件，它們往往是在grunt的某個(gè)版本的基礎(chǔ)上開(kāi)發(fā)的，而在他們的代碼中并不會(huì)出現(xiàn)require("grunt")這樣的依賴(lài)，dependencies配置里邊也不會(huì)寫(xiě)上grunt的依賴(lài)，為了說(shuō)明此模塊只能作為插件跑在宿主的某個(gè)版本范圍下，可以配置peerDependencies：

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

上面這個(gè)配置確保再npm install的時(shí)候tea-latte會(huì)和2.x版本的tea一起安裝，而且它們兩個(gè)的依賴(lài)關(guān)系是同級(jí)的： ├── tea-latte@1.3.5 └── tea@2.2.0 這個(gè)配置的目的是讓npm知道，如果要使用此插件模塊，請(qǐng)確保安裝了兼容版本的宿主模塊。

bundledDependencies

上面的單詞少個(gè)d，寫(xiě)成bundleDependencies也可以。 指定發(fā)布的時(shí)候會(huì)被一起打包的模塊。

optionalDependencies

如果一個(gè)依賴(lài)模塊可以被使用， 同時(shí)你也希望在該模塊找不到或無(wú)法獲取時(shí)npm繼續(xù)運(yùn)行，你可以把這個(gè)模塊依賴(lài)放到optionalDependencies配置中。這個(gè)配置的寫(xiě)法和dependencies的寫(xiě)法一樣，不同的是這里邊寫(xiě)的模塊安裝失敗不會(huì)導(dǎo)致npm install失敗。 當(dāng)然，這種模塊就需要你自己在代碼中處理模塊確實(shí)的情況了，例如：

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 中的配置會(huì)覆蓋dependencies中的配置，最好只在一個(gè)地方寫(xiě)。

engines

你可以指定項(xiàng)目運(yùn)行的node版本范圍，如下： { "engines" : { "node" : ">=0.10.3 <0.12" } } 和dependencies一樣，如果你不指定版本范圍或者指定為*，任何版本的node都可以。 也可以指定一些npm版本可以正確的安裝你的模塊，例如： { "engines" : { "npm" : "~1.0.20" } } 要注意的是，除非你設(shè)置了engine-strict屬性，engines屬性是僅供參考的。

engineStrict

注意：這個(gè)屬性已經(jīng)棄用，將在npm 3.0.0 版本干掉。

os

可以指定你的模塊只能在哪個(gè)操作系統(tǒng)上跑： "os" : [ "darwin", "linux" ] 也可以指定黑名單而不是白名單： "os" : [ "!win32" ] 服務(wù)的操作系統(tǒng)是由process.platform來(lái)判斷的，這個(gè)屬性允許黑白名單同時(shí)存在，雖然沒(méi)啥必要這樣搞...

cpu

限制模塊只能在某某cpu架構(gòu)下運(yùn)行 "cpu" : [ "x64", "ia32" ] 同樣可以設(shè)置黑名單: "cpu" : [ "!arm", "!mips" ] cpu架構(gòu)通過(guò) process.arch 判斷

preferGlobal

如果您的軟件包主要用于安裝到全局的命令行應(yīng)用程序，那么該值設(shè)置為true ，如果它被安裝在本地，則提供一個(gè)警告。實(shí)際上該配置并沒(méi)有阻止用戶(hù)把模塊安裝到本地，只是防止該模塊被錯(cuò)誤的使用引起一些問(wèn)題。

private

如果這個(gè)屬性被設(shè)置為true，npm將拒絕發(fā)布它，這是為了防止一個(gè)私有模塊被無(wú)意間發(fā)布出去。如果你只想讓模塊被發(fā)布到一個(gè)特定的npm倉(cāng)庫(kù)，如一個(gè)內(nèi)部的倉(cāng)庫(kù)，可與在下面的publishConfig中配置倉(cāng)庫(kù)參數(shù)。

publishConfig

這個(gè)配置是會(huì)在模塊發(fā)布時(shí)用到的一些值的集合。如果你不想模塊被默認(rèn)被標(biāo)記為最新的，或者默認(rèn)發(fā)布到公共倉(cāng)庫(kù)，可以在這里配置tag或倉(cāng)庫(kù)地址。

DEFAULT VALUES

npm設(shè)置了一些默認(rèn)參數(shù)，如：·"scripts": {"start": "node server.js"} 如果模塊根目錄下有一個(gè)server.js文件，那么npm start會(huì)默認(rèn)運(yùn)行這個(gè)文件。 "scripts":{"preinstall": "node-gyp rebuild"} 如果模塊根目錄下有binding.gyp, npm將默認(rèn)用node-gyp來(lái)編譯preinstall的腳本 "contributors": [...] 若模塊根目錄下有AUTHORS 文件，則npm會(huì)按Name (url)格式解析每一行的數(shù)據(jù)添加到contributors中，可以用#添加行注釋.

參考文檔列表

• 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)

總結(jié)

到此這篇關(guān)于你可能不知道的package.json屬性的文章就介紹到這了,更多相關(guān)package.json屬性?xún)?nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論