package.json裏的一些屬性講解

內容來自 npm官方文檔 , 本文作中文解釋.

name, version

首先, 包名字是必須的. 版本號也是必須的.

npm規定了, 一個package是由名字加版本號做爲惟一標識的.

好比 express@4.2.0 , koa@2.1.1 , 不一樣的包名或者版本號, 對應的內容是不同的.

以上內容比較好理解, 接下來我補充幾點:

• 包名必須少於等於 214 字符,
• 包名不能以 .或_開頭
• 包名不能含有大寫字母 (歷史緣由, 有的老包還有大寫字母,新的已經不能用大寫字母)
• 另外, 一些URL規範裏不容許的字符也不能用(具體哪些字符就須要你們本身查查了)
• 建議不要在包名裏包含js`node`等字眼, 由於npm默認就是js或node的
• 由於包名最終會用在require語句裏, 因此儘量短一些,但要注意能明確表達本身的用途
• 你開發一個包以前, 最好本身上 npm官網看看名字是否是已經被佔用了(很重要)

對於版本號, npm使用業界標準的 {major}.{feature}.{patch} 模式

因此 1.4.1到1.4.2多是修復個小bug

1.4.1到1.5.0多是加了新功能

1.4.1到2.0.0的話, 可能就是變化很大的兩個東西了.

Tips

若是你要發佈包到npm, 相同的包名, 相同的版本號, 只能發佈一次,

因此若是你修改了代碼, 須要更新版本號才能publish,

具體修改哪一位, 要看你修改了多少東西.

description, keywords

這兩個放在一塊兒講.

這兩個字段都是用來在npm官網上搜索的, 區別是一個是字符串, 一個是字符串數組.

不難理解, npm會對description作分詞搜索, 而對於 keywords會作精準搜索.

Tips

官方並未說明, 以上關於分詞與否, 純屬猜想.

homepage

若是你有時間, 能夠爲你的包作一個官網之類的, 大型的項目常見.

bugs

這個字段並非說這個包還有 bug, 首先咱們看看例子

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

這個字段實際上是提供給使用者上報 bugs的途徑, 能夠填一個email或者一個issue地址

Tips

若是你只想提供一個issue地址, 那麼bugs能夠只是一個字符串

license

這個......不想多說, 自行了解吧

author, contributors

這是關於做者或者其餘開發人員信息的字段, 含義很好理解, 咱們看一個例子:

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

author和contributors就是放置型如上面這樣的對象來描述人物信息的, 區別是, author是單個, 而contributors是數組.

Tips

非必須信息, 能夠出名之後再加.

files

這個不是必選項, 也並不常見, 可是很重要, 由於有配置這個信息會顯得很是專業.

files是一個數組, 它描述了你 npm publish的時候推送到npm服務器的文件列表,支持目錄和通配 好比

"files": [
    "LICENSE",
    "History.md",
    "Readme.md",
    "index.js",
    "lib/"
  ],

反過來, 你能夠經過一個 .npmignore 文件來排除一些文件, 防止大量的垃圾文件推送到npm, 規則上和你用的gitignore是同樣的.

Tips

若是你的項目下有 .gitignore 文件, 那麼它也能充當.npmignore的功能.

這意味着, 若是沒有特別的需求, 一個.gitignore就好了.

main

這個是一個重要屬性,原文對這個描述比較繞, 實際上能夠理解爲 入口文件

"main":"./src/index.js",

以上面的例子來講, 若是你的包名是foo, 當用戶代碼require('foo')時,

至關於require了你包目錄下的 ./src/index.js文件.

若是沒有提供這個字段, 默認是項目根目錄下的index.js

bin

這也是一個重要屬性, 它定義了一系列可執行命令, 在全局安裝的命令行包裏尤爲多見.

這裏提供一個pm2的bin例子:

"bin": {
    "pm2": "./bin/pm2",
    "pm2-dev": "./bin/pm2-dev",
    "pm2-docker": "./bin/pm2-docker",
    "pm2-runtime": "./bin/pm2-runtime"
},

上面這個對象的意思是, 安裝完之後, 輸入pm2其實是運行{模塊所在目錄}/bin/pm2, 以此類推.

帶有bin信息的包, 在局部安裝後, 可執行文件會在./node_modules/.bin下,

若是是全局安裝, 可執行文件會在 $PATH 裏對應npm那個目錄下.

Tips

有些朋友安裝node環境的方式比較奇怪, 沒有把全局安裝nodule的路徑加到 $PATH裏,

致使 npm install -g 之後提示命令找不到, 最好檢查一下本身的$PATH

man

這裏是manuel, 是手冊的意思, 不是男人, 也不是上面說到的main

這個是指定一個(或多個)文件, 用於執行man {包名}時, 展示給用戶的手冊內容.

稍微有點linux基礎都懂, 不細說.

directories

這個字段挺無語的, 它是一個object, 包含了lib`binmandocexampletest`等屬性,

主要是用來告訴用戶個人某些功能目錄放在哪裏, 也是一個顯得專業的功能.

除此之外暫時沒有實際應用.

"directories": {
    "bin": "./bin",
    "doc": "./doc",
    "lib": "./lib",
    "man": "./man"
},

repository

這個屬性很明顯, 是放置你的git地址的, 格式以下:

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

Tips

這個部分有一些縮寫的方式, 本身看原文吧.

scripts

這個是重點!

"scripts": {
    "start": "node app.js",
    "any": "any command && exit 0",
},

以上兩個配置, 提供了 npm start和npm run any兩個命令對應的實際操做.

至於何時須要run何時不須要,

能夠詳細看 npm scripts, 這個夠單獨開一章來講明.

Tips

除了定義一些快捷命令, scripts 還有一些鉤子性質的預約義命令,

如 preinstall , postinstall 能夠在包安裝先後 自動 執行一些操做

詳細仍是看上面的連接.

config

這是一個object結構, 定義了一些執行scripts時的配置參數之類, 和scripts屬性關係很大, 我的目前還沒用過, 等我研究好了再補充.

目前能夠參考 npm-config

dependencies, devDependencies, peerDependencies

前兩個你們很熟悉了, 不用展開講了, 惟一須要提醒的是, 要本身判斷什麼包安裝在dev就行.

值得注意的是 peerDependencies 這個並不常見的屬性,

它是用於你這個包並不依賴模塊A, 可是要使用你這個包, 必須當前項目裝了A.

好比你的 my-project , 已經引入了people模塊, 而還有一個people-fly, 必須你的my-project有用到people才能夠用, 可是people-fly的源碼裏並無直接使用people.

這時候, people-fly的package.json 裏就會聲明peerDependencies包含people

以上這一段多讀幾回應該能理解的.

bundledDependencies

這個是一個特定場景的屬性, 我我的沒用過.

bundledDependencies是一個字符串數組, 內容只能是在dependencies, devDependencies兩個裏面聲明過的包才行.

這樣能夠在npm publish和npm pack的時候將一些依賴打包進去.

Tips:

單純聲明在dependencies裏的包, 會在安裝的時候, 再從npm那邊安裝一遍.

而打包了的, 就會在當前模塊安裝的時候, 就一併下載下來了.

具體怎麼應用就本身想一想吧, 我沒用過.

optionalDependencies

無關緊要的依賴?

npm一般會在某些依賴安裝失敗時報錯, 中斷操做, 而寫在optionalDependencies的依賴則不會.

要妥善支持這個功能, 你的源碼裏面也要注意判斷這些特定的依賴是否存在.

實際上是很麻煩很扯淡的操做.

engines

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

這個屬性能夠聲明你的包須要在怎樣的node環境下運行 (npm也同樣能夠聲明)

只不過,

只有在用戶配置 npm 的engine-strict後, 纔會有意義, 否則只會冒出一個 warning (程序員看不到 warning)

engineStrict

忽略, 最新的 npm已經廢棄這個了.

os

看兩個例子

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

"os" : [ "!win32" ]

顯然意見就是操做系統的黑白名單,

好比你開發了一個工具, 只支持OSX, 不支持Windows (這合情合理!)

就能夠經過這個來聲明.

cpu

看兩個例子

"cpu" : [ "x64", "ia32" ]

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

不想解釋了, 能玩到這個屬性的人, 已經不須要看這個了.

private

這個設置爲true, 就會沒法npm publish,

怎麼說呢, 有用的吧.?

publishConfig

定義一個包在發佈到npm時的一些配置項,

要看具體細節請看 npm-config

更多...

package.json其實就是一個json文件, 你賦予一些字段更多的功能, 它就有了意義, 你本身開發功能的時候, 能夠任意 發明 一些字段進去, 只要是你有用的就行.

好比我最近的一個項目, 在package.json里加了一個ci_cd對象, 你懂的.