最全的package.json解析

目錄

1. 概述

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

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

比如下面這個(gè)文件，只存在簡(jiǎn)單的項目名稱(chēng)和版本號。

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

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

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

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

{
    "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字段，這兩項是必填的。名稱(chēng)和版本一起構成一個(gè)標識符，該標識符被認為是完全唯一的。對包的更改應該與對版本的更改一起進(jìn)行。
name必須小于等于214個(gè)字符，不能以.或_開(kāi)頭，不能有大寫(xiě)字母，因為名稱(chēng)最終成為URL的一部分因此不能包含任何非URL安全字符。
npm官方建議我們不要使用與核心節點(diǎn)模塊相同的名稱(chēng)。不要在名稱(chēng)中加js或node。如果需要可以使用engines來(lái)指定運行環(huán)境。
該名稱(chēng)會(huì )作為參數傳遞給require，因此它應該是簡(jiǎn)短的，但也需要具有合理的描述性。

3. version字段

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

4. description字段

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

5. keywords字段

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

6. homepage字段

homepage項目的主頁(yè)地址。

7. bugs字段

bugs用于項目問(wèn)題的反饋issue地址或者一個(gè)郵箱。

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

8. license字段

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

9. author字段 contributors字段

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

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

也可以寫(xiě)成一個(gè)字符串

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

10. files字段

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

11. main字段

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

12. bin字段

bin項用來(lái)指定每個(gè)內部命令對應的可執行文件的位置。如果你編寫(xiě)的是一個(gè)node工具的時(shí)候一定會(huì )用到bin字段。
當我們編寫(xiě)一個(gè)cli工具的時(shí)候，需要指定工具的運行命令，比如常用的webpack模塊，他的運行命令就是webpack。

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

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

13. man字段

man用來(lái)指定當前模塊的man文檔的位置。

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

14. directories字段

directories制定一些方法來(lái)描述模塊的結構, 用于告訴用戶(hù)每個(gè)目錄在什么位置。

15. repository字段

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

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

16. scripts字段

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

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

使用scripts字段可以快速的執行shell命令，可以理解為alias。
scripts可以直接使用node_modules中安裝的模塊，這區別于直接運行需要使用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

用戶(hù)可以通過(guò)npm config set來(lái)修改這個(gè)值。

npm config set yindong:port 8000

18. dependencies字段, devDependencies字段

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

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

當安裝依賴(lài)的時(shí)候使用--save參數表示將該模塊寫(xiě)入dependencies屬性，--save-dev表示將該模塊寫(xiě)入devDependencies屬性。

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

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

版本說(shuō)明

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

19. peerDependencies字段

當我們開(kāi)發(fā)一個(gè)模塊的時(shí)候，如果當前模塊與所依賴(lài)的模塊同時(shí)依賴(lài)一個(gè)第三方模塊，并且依賴(lài)的是兩個(gè)不兼容的版本時(shí)就會(huì )出現問(wèn)題。

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

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

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

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

注意，從npm 3.0版開(kāi)始，peerDependencies不再會(huì )默認安裝了。就是初始化的時(shí)候不會(huì )默認帶出。

20. bundledDependencies字段

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

21. optionalDependencies字段

如果一個(gè)依賴(lài)模塊可以被使用， 同時(shí)你也希望在該模塊找不到或無(wú)法獲取時(shí)npm繼續運行，你可以把這個(gè)模塊依賴(lài)放到optionalDependencies配置中。這個(gè)配置的寫(xiě)法和dependencies的寫(xiě)法一樣，不同的是這里邊寫(xiě)的模塊安裝失敗不會(huì )導致npm install失敗。

22. engines字段

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

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

23. os字段

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

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

24. cpu字段

限制模塊只能在某種架構的cpu下運行

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

25. private字段

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

"private": true

26. publishConfig字段

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

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

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

27. preferGlobal字段

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

"preferGlobal": false

28. browser字段

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

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

參考來(lái)源

[1]
[2]

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