Node學習之package.json

什麼是package.json

Node.js項目遵循模塊化的架構，當我們創建一個Node.js項目，意味着創建了一個模塊，這個模塊的描述文件，被稱爲package.json

它包含了運行項目所需要的各種依賴、項目配置信息

創建package.json

快速創建

npm init -y

package.json

{
  "name": "demo",
  "version": "1.0.0",
  "description": "",
  "main": "main.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

字段介紹

必填字段 name & version

如果你打算髮布npm包，name和verson是package.json中的必填字段，它們組成一個npm模塊的唯一標識。

如果你不打算髮布npm包，則這兩個字段是可選的

name

name字段定義模塊的名稱

官方規則：

• 名稱必須小於等於214個字符
• 名稱不能以點或下劃線開頭。
• 不得包含大寫字母
• 該名稱最終成爲URL，命令行參數和文件夾名稱的一部分。 因此，該名稱不能包含任何非URL安全的字符。（使用validate-npm-package-name包檢測模塊名是否合法）

官方建議：

• 不能與Node核心模塊同名
• name名不能與npm其他模塊名重複，可以執行npm view <packageName>查看模塊名是否已被使用，未被使用會拋出404錯誤。或者去https://www.npmjs.com/上搜索模塊名
• 不要再名稱中添加js或node
• 名稱可能會作爲參數傳遞給require()，因此它應該簡短，並具有描述性

名稱可以可選的以範圍爲前綴，例如@babel/present

version

npm包中的模塊版本都需要遵循SemVer規範，該規範採用X.Y.Z格式，X、Y、Z均爲非負整數，且禁止在數字前補零

• X 主版本號：有大變動，且向下不兼容
• Y 次版本號：新增功能，但是向下兼容
• Z 補丁版本號：修復問題

先行版本

當某個版本改動比較大、並非穩定而且可能無法滿足預期的兼容性需求時，可能需要先發佈一個先行版本。

先行版本號一般加到修訂號後，通過-連接一串以.分隔的標識符和版本編譯信息，如：3.10.2-beta.13。

標識符：

• 內部版本(alpha)
• 公測版本(beta)
• 正式版本的候選版本(rc:Release candiate)

校驗版本號

版本號必須可以通過node-semver進行解析

npm view <packageName> version # 查看最新版本
npm view <packageName> versions # 查看歷史版本

描述信息 description & keywords

• description字段添加模塊的描述信息
• keywords字段添加模塊的關鍵字

使用npm檢索模塊時會對這兩個字段進行匹配

安裝項目依賴 dependencies & devDependencies

dependencies、 devDependencies是包含項目依賴的對象，對象將包名key映射到版本範圍value。

• dependencies字段指定了項目運行時所依賴的模塊（生產環境使用），如antd moment loadsh等插件庫
  • 當把項目作爲一個npm包時，用戶安裝時只會安裝dependencies中的依賴
• devDependencies字段指定了項目開發時所依賴的模塊（開發環境使用），如webpack babel typescript等
  • 開發時對代碼校驗、編譯打包等操作時需要的依賴，在提交線上運行時並不需要，所以放到devDependencies中。例如開發自己的項目而不是對外的包，上面的antd moment loadsh會被打包到發佈代碼中，也可以放到devDependencies中

添加依賴並記錄到package.json

# npm
npm install <packageName> --save # 寫入dependencies屬性
npm install <packageName> --save-dev # 寫入devDependencies屬性

# yarn
yarn add <packageName> # 寫入dependencies屬性
yarn add <packageName> --dev # 寫入devDependencies屬性

線上或開發環境安裝package.json中的依賴

# npm
npm install # 安裝所有依賴（dependencies 和 devDependencies）
npm install --production # 安裝生產依賴（dependencies）

# yarn
yarn install # 安裝所有依賴（dependencies 和 devDependencies）
yarn install --production # 安裝生產依賴（dependencies）

版本範圍

[標識符][主版本號].[次版本號].[補丁版本號]版本號標識符定義在安裝依賴時，允許更新到的版本範圍

version

完全比配版本號

比較version

• >version 大於版本號的範圍
• >=version 大於等於版本號的範圍
• <version小於版本號的範圍
• <=version小於等於版本號的範圍

~version 大約等於

示例	版本範圍	說明
~X.Y.Z	X.Y.Z<=version<X.(Y+1).0	允許補丁版本號升級，無上限，下限爲Z
~X.Y	X.Y.0<=version<X.(Y+1).0	允許補丁版本號升級，無上限
~X	X.0.0<=version<(X+1).0.0	允許次版本號和補丁版本號升級，無上限

^version與版本兼容

在未缺失的版本號中，從左往右，找到第一個不爲0的版本號，它後面的版本號允許升級到最新。

版本號缺失，視爲0

次版本號和補丁版本號都缺失，同時主版本爲0，補丁版本號視爲1

版本號缺失，允許升級

示例	版本範圍	說明
^1.3.4	1.3.4<=version<2.0.0	主版本號不爲0，允許次版本號和補丁版本號升級，有下限，無上限
^0.3.4	0.3.4<=version<0.4.0	主版本號爲0，次版本號不爲0，允許補丁版本號升級，有下限，無上限
^0.0.4	0.0.4<=version<0.0.5	主版本號和次版本號都爲0，無法升級模塊
^0.3	0.3.0<=version<0.4.0	主版本號爲0，次版本號不爲0，補丁版本號缺失視爲0，允許升級補丁版本號，無上限
^0	0.0.1<=version<1.0.0	主版本號爲0，次版本號和補丁版本號缺失，補丁版本號視爲1，允許次版本號和補丁版本號升級，次版本號下限1
^1.3	1.3.0<=version<2.0.0	主版本號不爲0，允許次版本號和補丁版本號升級，次版本號下限3
^1	1.0.0<=version<2.0.0	主版本號不爲0，次版本號和補丁版本號缺失，都視爲0，允許次版本號和補丁版本號升級

腳本管理 scripts

生命週期事件

scripts包含在包的生命週期中各個時間運行的腳本命令。

• key是生命週期時間，install、postinstall、publish等
• value是時間點運行的命令

簡化終端命令

scripts還是包含自定義腳本命令

• key可以通過npm run <key>運行的腳本
• value爲實際運行的命令

默認值

• start：node server.js
  • 如果項目根目錄下有一個server.js文件，則npm run start(可省略爲npm start)將默認執行node server.js命令
• install：node-gyp rebuild
  • 如果項目根目錄下有一個binding.gyp文件，並且還未定義install和preinstall腳本，npm將默認使用node-gyp rebuild編譯install命令

package.json vars

scripts運行的腳本可以訪問到package.json定義的屬性

訪問方式：process.env.npm_package_[propName]

定義項目入口 main

• 如果你的項目是一個npm包，當用戶安裝包後，require()返回的是main字段中所列出的文件的module.exports屬性
• 當不指定main字段時，默認時模塊根目錄下面的index.js文件

發佈文件配置 files

• files是一個包含文件/目錄列表的數組
• 用於描述使用npm publish命令推送到npm服務器的文件列表，如果指定爲文件夾，則文件夾內所有內容都會包含進來。省略該字段，默認爲[*]
• 也就是安裝依賴時，下載的文件內容
• 另外還可以通過配置一個.npmignore文件來排除一些文件，防止大量的垃圾文件推送到npm上。工作原理與.gitignore一樣，如果存在.gitignore，缺少.npmignore，則改用.gitignore的內容。
• 無法通過.gitignore和.gitignore排除files字段中包含的文件。

禁止發佈 private

設置private爲true，npm將拒絕發佈該私有模塊，可以放置非開源項目意外發布

指定模塊適用系統 os

如果模塊只能運行在A系統，我們需要保證其他系統的用戶不會安裝到該模塊，設置os可以指定模塊適用的系統，或指定不能安裝的系統黑名單

"os": ["darwin","linux"] # 適用系統
"os": ["!win32"] # 黑名單系統，此列表中的系統安裝模塊會報錯

指定模塊適用CPU架構 cpu

同os一樣配置適用列表和黑名單列表

指定項目node版本 engines

engines可以指定node版本或npm版本，在安裝時對不適用的版本發出警告

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

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

自定義命令 bin

bin字段指定內部命令對應的可執行文件的位置。

例如：

• vue-cli的vue create
• create-react-app的create-react-app

當用戶安裝帶有bin字段的包時

• 如果是全局安裝，npm將使用符號鏈接把這些文件鏈接到usr/local/node_modules/.bin/
• 如果是本地安裝，會鏈接到./node_modules/.bin/
  示例：

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

node node_modules/.bin/myapp

• 當需要node環境時需要加上node前綴
• 使用node執行，就要對命令添加路徑前綴node_modules/.bin/，否則就會在當前路徑下尋找cli.js

在可執行文件的第一行加上#!/usr/bin/env node，用於指明該腳本要使用node執行

• /usr/bin/env 告訴用戶到path目錄下去尋找node
• #!/usr/bin/env node 可以讓系統動態的去查找node，以解決不同用戶設置不一致的問題

加上後，就可以直接使用myapp執行了

參考

重新認識 package.json
npm-package.json