package.json 詳解

翻譯：瘋狂的技術宅

原文：heynode.com/tutorial/wh…

未經允許嚴禁轉載

Node 專案在專案根目錄中名為 package.json 的檔案中跟蹤依賴關係和後設資料。這是你專案的核心。它包含名稱、描述和版本之類的資訊，以及執行、開發以及有選擇地將專案釋出到 NPM 所需的資訊。

在本教程中，我們將：

• 瞭解 package.json 與專案之間的關係
• 確定重要欄位和後設資料
• 瞭解如何管理 package.json

目標

瞭解什麼是 package.json 檔案，它與你專案的關係以及需要了解的常見屬性。

瞭解 package.json

如果你以前用過 Node.js，則可能會遇到 package.json 檔案。它是一個 JSON 檔案，位於專案的根目錄中。你的 package.json 包含關於專案的重要資訊。它包含關於專案的使人類可讀後設資料（如專案名稱和說明）以及功能後設資料（如程式包版本號和程式所需的依賴項列表）。

package.json 示例如下所示：

 {
        "name": "my-project",
        "version": "1.5.0",
        "description": "Express server project using compression",
        "main": "src/index.js",
        "scripts": {
            "start": "node index.js",
			"dev": "nodemon",
			"lint": "eslint **/*.js"
        },
        "dependencies": {
            "express": "^4.16.4",
			"compression": "~1.7.4"
        },
        "devDependencies": {
			"eslint": "^5.16.0",
            "nodemon": "^1.18.11"
        },
		"repository": {
			"type": "git",
			"url": "https://github.com/osiolabs/example.git"
		},
		"author": "Jon Church",
		"contributors": [{
			"name": "Amber Matz",
			"email": "example@example.com",
			"url": "https://www.osiolabs.com/#team"
		}],
		"keywords": ["server", "osiolabs", "express", "compression"]
    }
複製程式碼

package.json 的用途是什麼？

專案的 package.json 是配置和描述如何與程式互動和執行的中心。 npm CLI（和 yarn）用它來識別你的專案並瞭解如何處理專案的依賴關係。package.json 檔案使 npm 可以啟動你的專案、執行指令碼、安裝依賴項、釋出到 NPM 登錄檔以及許多其他有用的任務。 npm CLI 也是管理 package.json 的最佳方法，因為它有助於在專案的整個生命週期內生成和更新 package.json 檔案。

package.json 會在專案的生命週期中扮演多個角色，其中某些角色僅適用於釋出到 NPM 的軟體包。即使你沒有把專案釋出到 NPM 登錄檔中，或者沒有將其公開發布給其他人，那麼 package.json 對於開發流程仍然至關重要。

你的專案還必須包含 package.json，然後才能從 NPM 安裝軟體包。這可能是你在專案中需要它的主要原因之一。

package.json 中的常見欄位

讓我們看一下 package.json 中包含的一些最常見和重要的欄位，以更好地瞭解如何使用和管理這個基本檔案。有些用來發布到 NPM，而其他一些則可以幫助 npm CLI 執行應用程式或安裝依賴項。

實際的欄位比我們所介紹的要多，你可以在它的文件中瞭解其餘欄位，但以下的是必須要了解的 package.json 屬性。

name

"name": "my-project"
複製程式碼

name 欄位定義包的名稱。釋出到 NPM 登錄檔時，這是軟體包將在其中顯示的名稱。它不能超過 214 個字元，只能是小寫字母，並且必須是URL安全的（允許連字元和下劃線，但 URL 中不允許使用空格或其他字元）。

如果將軟體包釋出到 NPM，則 name 屬性是必需的，並且必須是唯一的。如果嘗試用 NPM 登錄檔上當前已經使用的名稱釋出程式包，則會收到錯誤訊息。如果你的軟體包並不是要釋出到 NPM 上，則 name 不必是唯一的。

version

"version": "1.5.0",
複製程式碼

version 欄位對於任何已釋出的軟體包都非常重要，並且在釋出之前是必填的。這是 package.json 描述的軟體的當前版本。

你不需要使用 SemVer，但它是 Node.js 生態系統中使用的標準，強烈建議使用。對於未釋出的程式包，此屬性不是嚴格要求的。通常在將新版本釋出到 NPM 之前，根據 SemVer，版本號會增加。當不依賴程式包作為依賴項或未將程式包釋出到 NPM 時，通常不使用這個工作流程。但是如果將軟體包用作依賴項，那麼確保 version 欄位保持最新非常重要，這樣可以確保其他人所使用的軟體包的正確版本。 瞭解有關語義版本控制（semantic versioning）的更多資訊。

license

這是非常重要但經常被忽略的屬性。license 欄位使我們可以定義適用於 package.json 所描述程式碼的許可證。同樣，在將專案釋出到 NPM 登錄檔時，這非常重要，因為許可證可能會限制某些開發人員或組織對軟體的使用。擁有清晰的許可證有助於明確定義該軟體可以使用的術語。

license 欄位的值通常是許可證的識別符號程式碼——例如 MIT 或 ISC 之類的字串，它們代表MIT 許可證和 ISC 許可證。如果你不想提供許可證，或者明確不想授予使用私有或未釋出的軟體包的許可權，則可以將 UNLICENSED 作為許可證。如果你不確定要使用哪個許可證， Choose a License 是對你有用的資源。

author 和 contributors

"author": "Jon Church jon@example.com https://www.osioslabs.com/#team",
"contributors": [{
	"name": "Amber Matz",
	"email": "example@example.com",
	"url": "https://www.osiolabs.com/#team"
}],
複製程式碼

author 和 contributors 欄位的功能類似。它們都是 people 欄位，可以是"Name" 格式的字串，也可以是具有 name，email，url 欄位的物件。email 和 url 都是可選的。

author 只供一個人使用，contributors 則可以由多個人組成。

這些欄位是列出公共專案的聯絡人以及與貢獻者共享信用的有用方法。

description

NPM 登錄檔將description 欄位用於釋出的軟體包，以在搜尋結果中和 npmjs.com 網站上描述該軟體包。

當使用者搜尋 NPM 登錄檔時，該字串用於幫助瞭解軟體包。這應該是軟體包的簡短摘要。

即使你沒有將其釋出到 NPM 登錄檔中，它也可以用作專案的簡單文件。

keywords

"keywords": ["server", "osiolabs", "express", "compression"]
複製程式碼

keywords 欄位是一個字串陣列，其作用與描述相似。 NPM 登錄檔會為該欄位建立索引，能夠在有人搜尋軟體包時幫助找到它們。陣列中的每個值都是與你的程式包關聯的一個關鍵字。

如果你不釋出到 NPM 登錄檔，則這個欄位用處不大，可以忽略它。

main

"main": "src/index.js",
複製程式碼

main 欄位是 package.json 的功能屬性。它定義了專案的入口點，通常是用於啟動專案的檔案。

如果你的包（例如其名稱為 foo-lib）是由使用者安裝的，則當使用者執行 require('foo-lib') 時，這是 require 返回的 main 欄位中所列出的檔案的 module.exports 屬性。

它的值通常是專案根目錄中的 index.js 檔案，但也可以是你選擇作為包的主入口的任何檔案。

scripts

"scripts": {
	"start": "node index.js",
	"dev": "nodemon"
}
複製程式碼

scripts 欄位是 package.json 中的另一種後設資料功能。scripts 屬性接受一個物件，它的值為可以通過 npm run 執行的指令碼，其鍵為實際執行的命令。這些通常是終端命令，我們把它們放入 scripts 欄位，可以既可以記錄它們又可以輕鬆地重用。

scripts 是 npm CLI 用來執行專案任務的強大工具。他們可以完成開發過程中的大多數任務。 瞭解有關 npm 指令碼的更多資訊。

repository

"repository": {
	"type": "git",
	"url": "https://github.com/osiolabs/example.git"
}
複製程式碼

你可以通過提供 repository 欄位來記錄專案程式碼所在的資源庫。該欄位是一個物件，用於定義原始碼所在的 url 及其使用的版本控制系統的型別。對於開源專案，可能是以 Git 作為版本控制系統的 GitHub 或 Bitbucket 。

需要注意的是 URL 欄位的本意是指向可從中訪問版本控制的位置，而不僅僅是指向已釋出的程式碼庫。

dependencies

"dependencies": {
	"express": "^4.16.4",
    "compression": "~1.7.4"
}
複製程式碼

這是 package.json 中最重要的欄位之一，它列出了專案使用的所有依賴項（專案所依賴的外部程式碼）。使用 npm CLI 安裝軟體包時，它將下載到你的 node_modules/ 資料夾中，並將一個條目新增到你的依賴項屬性中，注意軟體包的名稱和已安裝的版本。

dependencies 欄位是一個物件，其中的包名做為鍵，而版本或版本範圍為值。從這個列表中，當在目錄中執行 npm install 時，npm 知道要獲取和安裝哪些包（以及什麼版本）。 package.json 的 dependencies 欄位位於專案的核心，並定義專案所需的外部包。

在依賴版本中看到的插入符號（^）和波浪號（~）是 SemVer 中定義的版本範圍的表示法。 瞭解有關依賴版本和 SemVer 的更多資訊。

devDependencies

"devDependencies": {
	"nodemon": "^1.18.11"
}
複製程式碼

與 dependencies 欄位類似，但是這裡列出的包僅在開發期間需要，而在生產中不需要。

例如，在開發過程中使用工具重新載入專案，比如 nodemon，一旦程式部署並投入生產，將不會再使用它。devDependencies 屬性使我們可以明確地指出生產中不需要哪些依賴項。在生產環境中安裝應用程式時，可以用 npm install --production 僅安裝 package.json 的 dependency 欄位中列出的內容。

devDependency 是記錄開發過程中程式需要哪些工具的好方法。要將 npm 的軟體包作為 devDependency 安裝，可以執行 npm install --save-dev。

devDependencies 屬性的另一種用途是在我們的 npm 指令碼中使用它們。 瞭解有關在npm指令碼中使用 devDependencies 的更多資訊。

管理你的 package.json

package.json 檔案必須是有效的 JSON。這意味著任何缺少的逗號、丟失的引號或其他格式錯誤都將阻止 npm 與 package.json 進行互動。如果確實引入了錯誤，則下次執行 npm 命令時將會看到錯誤提示。建議儘可能使用 npm CLI 更新和管理 package.json，以避免意外將錯誤引 入package.json 中。

使用 npm init 建立你的 package.json 將有助於確保你生成有效的檔案。

最好使用 npm 的命令 npm install ，npm uninstall 和 npm update 來管理依賴項，這樣可以使你的 package.json 和 node_modules/ 資料夾保持同步。如果手動新增依賴項列表的話，需要你在把依賴項實際安裝到專案之前執行 npm install。

因為 package.json 僅是我們記錄依賴項的位置，而 node_modules/ 資料夾是安裝依賴項程式碼的實際位置，所以手動更新 package.json 的依賴項欄位不會立即將我們的狀態反映到 node_modules/ 資料夾。這就是為什麼要用 npm 幫助管理依賴項的原因，因為它會同時更新 package.json 和 node_modules/ 資料夾。

你當然可以在文字編輯器中手動編輯 package.json 並進行更改，只要你注意不要引入任何 JSON 格式錯誤，這對大多數字段都適用。但是我建議你儘可能使用 npm CLI 命令。

總結

package.json 檔案是 Node 專案的核心。它記錄了有關釋出到 NPM 之前所需要的專案的重要後設資料，它還定義了 npm 用於安裝依賴項、執行指令碼以及標識包的入口點的專案功能屬性。

並非 package.json 中所有欄位都適用於你，但是我們可以通過其在 package.json 檔案中記錄有關程式的資訊來獲得一些強大的好處。瞭解 package.json 的角色以及它與 npm 的關係是開發 Node.js 應用的重要組成部分，並且正日益成為 JavaScript 生態系統的重要組成部分。

進一步瞭解

• 你還可以使用什麼其他格式提供儲存庫？（docs.npmjs.com）
• 如何在你的 package.json 中新增 private 欄位影響釋出到NPM？（docs.npmjs.com ）

其他資源

• npm-package.json：npm 的 package.json 處理細節（docs.npmjs.com）
• 選擇開源許可證（choosealicense.com）

歡迎關注前端公眾號：前端先鋒，領取webpack全系列教程。