高階前端必會的package.json欄位知識詳解

概覽

本文重點講解前端專案的package.json檔案中，所涉及到的欄位含義和它的使用場景。
避免一些設定性的錯誤，提高專案的維護性。

name

如果專案是需要發版為npm包的，則name欄位是必須的。因為它涉及到npm包的命名。

舉個例子

筆者曾釋出過開源的npm包，名字是ping-url。
對應的原始碼package.json的定義如下：

{
  "name": "ping-url",
  "version": "1.0.3",
  "description": "Check the url is normally accessible or not"
  
  // other
}

如果專案是不需要發版成npm包的，則name欄位是可選的，不一定要設定。

name命名規範

• name字串長度，必須小於或等於214個字元。
• 同一作用域內的包，可以用.或_作為開始字元
• 不能使用大寫字母命名
• 因為name欄位，在下載npm包時，會應用於url中，所以不能帶任何不安全的URL字元。

不安全的URL字元

• 空格" "
• 大於小於號<>
• 方括號[]
• 花括號{}
• 豎線|
• 反斜槓
• 插入號^
• 百分比%

私源npm包怎麼命名？

格式：@[scope]/[name]。

舉個例子：

筆者想要釋出個私源是@leon，包名是ping-url的包，則name需要命名為：@leon/ping-url。

{
  "name": "@leon/ping-url",
  "version": "1.0.3"
}

安裝命令：npm install @leon/ping-url。

version

version欄位用於定義版本號。

如果專案是為釋出npm包，則必須包含此欄位。如果是普通的專案，則此欄位是可選的。

每次釋出的version，必須是唯一的，之前釋出的時候沒使用過的。
version 的命名規則和注意點，可以參考筆者的另一篇文章package.json怎麼管理依賴包版本？，這裡就不展開了。

description

description用於描述當前專案的概況。

如上圖所示，釋出的npm包，在搜尋結果中，可以直接顯示description內容，方便使用方直接瞭解包的功能。

keywords

圖中標籤在package.json中對應的定義：

"keywords": [
    "ping url",
    "ping host",
    "ping"
  ]

從上述例子可以很清晰地看出，keywords是標籤，用於標記當前專案的重點詞彙。同時，可以作為搜尋關鍵詞，提供給資源平臺使用，進行索引。

homepage

專案的官網主頁地址。

"homepage": "https://github.com/wall-wxk/ping-url"

專案有對應官網地址的話，可以在homepage中宣告。如果沒有的話，也可以像筆者這樣，放個github專案原始碼入口。

repository

專案的原始碼地址。

"repository": {
    "type": "git",
    "url": "https://github.com/wall-wxk/ping-url.git"
}

開源專案，這個欄位很重要。
因為有意向的共同作業者，可以通過欄位資訊，便捷地進入檢視專案原始碼。

license

專案的協定型別。

這個專案涉及到智慧財產權方面的知識。所以開源專案的時候，要重點考慮到底要用哪個協定，而不是無腦用MIT。 具體的可選協定列表，可檢視SPDX License List

author

作者資訊。

"author": {
    "name": "leon",
    "email": "582104384@qq.com",
    "url": "https://wangxiaokai.vip"
}

如果有興趣讓別人知道你是誰，這個欄位是必不可少的。

當然如果你的程式碼是shit mountain，這個欄位也可以讓別人知道是你寫的....

contributors

共同作業者資訊。

格式是一個物件陣列。物件內容和author一致。

"contributors": [{
    "name": "hanmeimei",
    "email": "hanmeimei@qq.com"
},{
    "name": "lihua",
    "email": "lihua@qq.com"
}]

files

宣告有哪些檔案，是需要作為依賴項，保留下來。
不然，執行npm publish進行釋出時，這些檔案是會自動遮蔽上傳的。
同理，也可以使用.npmignore檔案進行設定。

"files": [
    "dist/*.js",
    "lib"
]

如果沒有files欄位宣告，則這些檔案，都不會保留，npm包將不能使用。

main

使用npm包時，需要進行require(..)的操作。這個操作，會檢視main欄位，找到程式的主入口。

bin

工具性質的npm包，一定有bin欄位，對外暴露指令碼命令。

舉個例子

"bin": {
    "npg-cli": "bin/cli"
}

筆者釋出的npm-package-cli包，是用於生成npm包腳手架的工具，對外暴露了指令碼命令：npg-cli。詳情可檢視npm-package-cli。

使用方安裝npm-package-cli包後，npg-cli命令會進行註冊，可以在CMD中識別並執行。

scripts

專案指令碼命令。（PS：這個就不需要解釋了：））

需要注意的，一定要有約定俗成的規範指令碼命令，降低維護成本。
比如：

npm run start 專案啟動

npm run build 打包

dependencies、devDependencies、peerDependencies

依賴的使用性質劃分。詳細可檢視筆者的文章package.json怎麼管理依賴包版本？。

需要提及的一點：peerDependencies在npm包的依賴關係處理中，很重要。

舉個例子

UI元件庫leon-ui 依賴React版本16，那麼package.json中，應該用peerDependencies告知使用方，需要React 16。

"peerDependencies": {
    "react": ">=16.8.0"
}

大家還可以注意專案npm install時，控制檯會輸出一些依賴的WARN，就是peerDependencies在起作用。

private

private和釋出npm包相關。

當private: true時，npm會拒絕釋出當前專案。這是防止意外發布個人倉庫的一種保護方式。

publishConfig

用於定義釋出npm時，設定相關資訊。

舉個例子：

筆者釋出私源npm包，到自己的npm服務，可以設定如下：

"publishConfig": {
  "registry": "http://npm.wangxiaokai.vip/repository/",
  "access": "public",
  "tag": "leon-tag"
}

registry 釋出的npm私源地址

access 釋出有作用域的包（比如@leon/ping-url），必須要設定access。

tag 指定當前版本對應的標籤

如圖所示，右側即是標籤tag。

注意
如果沒有顯式指定tag，預設tag是latest

types

專案如果是用TypeScript寫的，則需要types欄位，對外暴露相關的型別定義。

module

性質等同於main欄位。module用於ES6規範的模組，只要支援ES6，會優先使用module入口。
這樣，程式碼也可以啟用tree shaking機制。

unpkg

CDN方式下，引入當前npm包的連結。

sideEffects

sideEffects格式：boolean | string[]。

sideEffects: false用於告知打包工具（webpack），當前專案無副作用，可以使用tree shaking優化。

sideEffects的值，也可以是一個檔案路徑組成的陣列。告知哪些檔案無副作用，可以使用tree shaking優化。

"sideEffects": [
    "a.js",
    "b.js"
]

注意點

"import xxx;"語句，只引入未使用，如果宣告了sideEffects，則會被tree shaking刪除掉。

並且，由於tree shaking只在production模式生效，所以本地開發會一切正常，生產環境很難及時發現這個問題。

當然， 樣式檔案使用"import xxx;"的方式引入，會進行保留。

engines

專案執行環境的要求宣告。

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

上述程式碼，告知node版本需要在0.10.3與15之間，才可以執行當前專案。
在不符合條件的環境中執行專案時，控制檯會有報錯輸出。

os

作業系統的要求宣告。

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

cpu

CPU的要求宣告。

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

workspaces

monorepo型別的專案，需要用到workspaces。它可以告知其他工具，當前專案的工作區間在哪裡。

{
  "name": "workspace-example",
  "workspaces": [
    "./packages/*"
  ]
}

具體怎麼在實戰中使用，可檢視筆者的另一篇文章使用Yarn與Lerna管理monorepo。

bugs

開源專案用於接收bug反饋。

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

參考

npm Docs

以上就是高階前端必會的package.json欄位知識詳解的詳細內容，更多關於前端package.json欄位的資料請關注it145.com其它相關文章！