1. 概述

從我們接觸前端開始，每個項目的根目錄下一般都會有一個package.json文件，這個文件定義了當(dāng)前項目所需要的各種模塊，以及項目的配置信息（比如名稱、版本、許可證等）。

當(dāng)運行npm install命令的時候，會根據(jù)package.json文件中的配置自動下載所需的模塊，也就是配置項目所需的運行和開發(fā)環(huán)境。

比如下面這個文件，只存在簡單的項目名稱和版本號。

{
  "name" : "yindong",
  "version" : "1.0.0",
}

package.json文件是一個JSON對象，這從他的后綴名.json就可以看出來，該對象的每一個成員就是當(dāng)前項目的一項設(shè)置。比如name就是項目名稱，version是版本號。

當(dāng)然很多人其實并不關(guān)心package.json的配置，他們應(yīng)用的更多的是dependencies或devDependencies配置。

下面是一個更完整的package.json文件，詳細(xì)解釋一下每個字段的真實含義。

{
    "name": "yindong",
    "version":"0.0.1",
    "description": "antd-theme",
    "keywords":["node.js","antd", "theme"],
    "homepage": "https://zhiqianduan.com",
    "bugs":{"url":"http://path/to/bug","email":"yindong@xxxx.com"},
    "license": "ISC",
    "author": "yindong",
    "contributors":[{"name":"yindong","email":"yindong@xxxx.com"}],
    "files": "",
    "main": "./dist/default.js",
    "bin": "",
    "man": "",
    "directories": "",
    "repository": {
  "type": "git",
  "url": "https://path/to/url"
 },
    "scripts": {
      "start": "webpack serve --config webpack.config.dev.js --progress"
    },
    "config": { "port" : "8080" },
    "dependencies": {},
    "devDependencies": {
        "@babel/core": "^7.14.3",
        "@babel/preset-env": "^7.14.4",
        "@babel/preset-react": "^7.13.13",
        "babel-loader": "^8.2.2",
        "babel-plugin-import": "^1.13.3",
        "glob": "^7.1.7",
        "less": "^3.9.0",
        "less-loader": "^9.0.0",
        "style-loader": "^2.0.0",
        "webpack": "^5.38.1",
        "webpack-cli": "^4.7.0",
        "webpack-dev-server": "^3.11.2"
    },
    "peerDependencies": {
        "tea": "2.x"
    },
    "bundledDependencies": [
        "renderized", "super-streams"
    ],
    "engines": {"node": "0.10.x"},
   "os" : [ "win32", "darwin", "linux" ],
    "cpu" : [ "x64", "ia32" ],
    "private": false,
    "publishConfig": {}
  }

2. name字段

package.json文件中最重要的就是name和version字段，這兩項是必填的。名稱和版本一起構(gòu)成一個標(biāo)識符，該標(biāo)識符被認(rèn)為是完全唯一的。對包的更改應(yīng)該與對版本的更改一起進行。
name必須小于等于214個字符，不能以.或_開頭，不能有大寫字母，因為名稱最終成為URL的一部分因此不能包含任何非URL安全字符。
npm官方建議我們不要使用與核心節(jié)點模塊相同的名稱。不要在名稱中加js或node。如果需要可以使用engines來指定運行環(huán)境。
該名稱會作為參數(shù)傳遞給require，因此它應(yīng)該是簡短的，但也需要具有合理的描述性。

3. version字段

version一般的格式是x.x.x, 并且需要遵循該規(guī)則。
package.json文件中最重要的就是name和version字段，這兩項是必填的。名稱和版本一起構(gòu)成一個標(biāo)識符，該標(biāo)識符被認(rèn)為是完全唯一的。每次發(fā)布時version不能與已存在的一致。

4. description字段

description是一個字符串，用于編寫描述信息。有助于人們在npm庫中搜索的時候發(fā)現(xiàn)你的模塊。

5. keywords字段

keywords是一個字符串組成的數(shù)組，有助于人們在npm庫中搜索的時候發(fā)現(xiàn)你的模塊。

6. homepage字段

homepage項目的主頁地址。

7. bugs字段

bugs用于項目問題的反饋issue地址或者一個郵箱。

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

8. license字段

license是當(dāng)前項目的協(xié)議，讓用戶知道他們有何權(quán)限來使用你的模塊，以及使用該模塊有哪些限制。
"license" : "BSD-3-Clause"

9. author字段 contributors字段

author是具體一個人，contributors表示一群人，他們都表示當(dāng)前項目的共享者。同時每個人都是一個對象。具有name字段和可選的url及email字段。

"author": {
  "name" : "yindong",
  "email" : "yindong@xx.com",
  "url" : "https://zhiqianduan.com/"
}

也可以寫成一個字符串

"author": "yindong yindong@xx.com (https://zhiqianduan.com/)"

10. files字段

files屬性的值是一個數(shù)組，內(nèi)容是模塊下文件名或者文件夾名，如果是文件夾名，則文件夾下所有的文件也會被包含進來（除非文件被另一些配置排除了）
可以在模塊根目錄下創(chuàng)建一個.npmignore文件，寫在這個文件里邊的文件即便被寫在files屬性里邊也會被排除在外，這個文件的寫法與.gitignore類似。

11. main字段

main字段指定了加載的入口文件，require導(dǎo)入的時候就會加載這個文件。這個字段的默認(rèn)值是模塊根目錄下面的index.js。

12. bin字段

bin項用來指定每個內(nèi)部命令對應(yīng)的可執(zhí)行文件的位置。如果你編寫的是一個node工具的時候一定會用到bin字段。
當(dāng)我們編寫一個cli工具的時候，需要指定工具的運行命令，比如常用的webpack模塊，他的運行命令就是webpack。

"bin": {
  "webpack": "bin/index.js",
}

當(dāng)我們執(zhí)行webpack命令的時候就會執(zhí)行bin/index.js文件中的代碼。
在模塊以依賴的方式被安裝，如果存在bin選項。在node_modules/.bin/生成對應(yīng)的文件，
Npm會尋找這個文件，在node_modules/.bin/目錄下建立符號鏈接。由于node_modules/.bin/目錄會在運行時加入系統(tǒng)的PATH變量，因此在運行npm時，就可以不帶路徑，直接通過命令來調(diào)用這些腳本。
所有node_modules/.bin/目錄下的命令，都可以用npm run [命令]的格式運行。在命令行下，鍵入npm run，然后按tab鍵，就會顯示所有可以使用的命令。

13. man字段

man用來指定當(dāng)前模塊的man文檔的位置。

"man" :[ "./doc/calc.1" ]

14. directories字段

directories制定一些方法來描述模塊的結(jié)構(gòu), 用于告訴用戶每個目錄在什么位置。

15. repository字段

指定一個代碼存放地址，對想要為你的項目貢獻代碼的人有幫助

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

16. scripts字段

scripts指定了運行腳本命令的npm命令行縮寫，比如start指定了運行npm run start時，所要執(zhí)行的命令。

"scripts": {
  "start": "node ./start.js"
}

使用scripts字段可以快速的執(zhí)行shell命令，可以理解為alias。
scripts可以直接使用node_modules中安裝的模塊，這區(qū)別于直接運行需要使用npx命令。

"scripts": {
  "build": "webpack"
}

// npm run build
// npx webpack

17. config字段

config字段用于添加命令行的環(huán)境變量。

{
  "name" : "yindong",
  "config" : { "port" : "8080" },
  "scripts" : { "start" : "node server.js" }
}

然后，在server.js腳本就可以引用config字段的值。

console.log(process.env.npm_package_config_port); // 8080

用戶可以通過npm config set來修改這個值。

npm config set yindong:port 8000

18. dependencies字段, devDependencies字段

dependencies字段指定了項目運行所依賴的模塊，devDependencies指定項目開發(fā)所需要的模塊。

它們的值都是一個對象。該對象的各個成員，分別由模塊名和對應(yīng)的版本要求組成，表示依賴的模塊及其版本范圍。

當(dāng)安裝依賴的時候使用--save參數(shù)表示將該模塊寫入dependencies屬性，--save-dev表示將該模塊寫入devDependencies屬性。

"devDependencies": {
        "webpack": "^5.38.1",
}

對象的每一項通過一個鍵值對表示，前面是模塊名稱，后面是對應(yīng)模塊的版本號。版本號遵循“大版本.次要版本.小版本”的格式規(guī)定。

版本說明

• 固定版本: 比如5.38.1，安裝時只安裝指定版本。
• 波浪號: 比如~5.38.1, 表示安裝5.38.x的最新版本（不低于5.38.1），但是不安裝5.39.x，也就是說安裝時不改變大版本號和次要版本號。
• 插入號: 比如ˆ5.38.1, ，表示安裝5.x.x的最新版本（不低于5.38.1），但是不安裝6.x.x，也就是說安裝時不改變大版本號。需要注意的是，如果大版本號為0，則插入號的行為與波浪號相同，這是因為此時處于開發(fā)階段，即使是次要版本號變動，也可能帶來程序的不兼容。
• latest: 安裝最新版本。

19. peerDependencies字段

當(dāng)我們開發(fā)一個模塊的時候，如果當(dāng)前模塊與所依賴的模塊同時依賴一個第三方模塊，并且依賴的是兩個不兼容的版本時就會出現(xiàn)問題。

比如，你的項目依賴A模塊和B模塊的1.0版，而A模塊本身又依賴B模塊的2.0版。
大多數(shù)情況下，這不構(gòu)成問題，B模塊的兩個版本可以并存，同時運行。但是，有一種情況，會出現(xiàn)問題，就是這種依賴關(guān)系將暴露給用戶。

最典型的場景就是插件，比如A模塊是B模塊的插件。用戶安裝的B模塊是1.0版本，但是A插件只能和2.0版本的B模塊一起使用。這時，用戶要是將1.0版本的B的實例傳給A，就會出現(xiàn)問題。因此，需要一種機制，在模板安裝的時候提醒用戶，如果A和B一起安裝，那么B必須是2.0模塊。

peerDependencies字段，就是用來供插件指定其所需要的主工具的版本?？梢酝ㄟ^peerDependencies字段來限制，使用myless模塊必須依賴less模塊的3.9.x版本.

{
  "name": "myless",
  "peerDependencies": {
    "less": "3.9.x"
  }
}

注意，從npm 3.0版開始，peerDependencies不再會默認(rèn)安裝了。就是初始化的時候不會默認(rèn)帶出。

20. bundledDependencies字段

bundledDependencies指定發(fā)布的時候會被一起打包的模塊.

21. optionalDependencies字段

如果一個依賴模塊可以被使用， 同時你也希望在該模塊找不到或無法獲取時npm繼續(xù)運行，你可以把這個模塊依賴放到optionalDependencies配置中。這個配置的寫法和dependencies的寫法一樣，不同的是這里邊寫的模塊安裝失敗不會導(dǎo)致npm install失敗。

22. engines字段

engines字段指明了該模塊運行的平臺，比如Node或者npm的某個版本或者瀏覽器。

{ "engines" : { "node" : ">=0.10.3 <0.12", "npm" : "~1.0.20" } }

23. os字段

可以指定你的模塊只能在哪個操作系統(tǒng)上運行

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

24. cpu字段

限制模塊只能在某種架構(gòu)的cpu下運行

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

25. private字段

如果這個屬性被設(shè)置為true，npm將拒絕發(fā)布它，這是為了防止一個私有模塊被無意間發(fā)布出去。

"private": true

26. publishConfig字段

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

通常publishConfig會配合private來使用，如果你只想讓模塊被發(fā)布到一個特定的npm倉庫，如一個內(nèi)部的倉庫。

"private": true,
"publishConfig": {
  "tag": "1.0.0",
  "registry": "https://registry.npmjs.org/",
  "access": "public"
}

27. preferGlobal字段

preferGlobal的值是布爾值，表示當(dāng)用戶不將該模塊安裝為全局模塊時（即不用–global參數(shù)），要不要顯示警告，表示該模塊的本意就是安裝為全局模塊。

"preferGlobal": false

28. browser字段

browser指定該模板供瀏覽器使用的版本。Browserify這樣的瀏覽器打包工具，通過它就知道該打包那個文件。

"browser": {
  "tipso": "./node_modules/tipso/src/tipso.js"
},

參考來源

[1] npm package.json
[2] javaScript標(biāo)準(zhǔn)參考教程

 到此這篇關(guān)于最全的package.json解析的文章就介紹到這了,更多相關(guān)package.json解析內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論