npm 生態系統

npm 是隨 Node.js 一起發行的套件管理器。它可以安裝套件、執行專案指令碼、將套件發佈至登錄站，以及記錄相依性解析結果，讓團隊能夠重現應用程式建置流程。

套件中繼資料 #

每個 npm 專案都由 package.json 描述。最重要的欄位用於識別套件、定義指令碼並宣告相依性：

{
  "name": "example-service",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test",
    "start": "node src/server.js"
  },
  "dependencies": {
    "fastify": "^5.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  },
  "engines": {
    "node": ">=20"
  }
}

生產環境需要使用 dependencies。devDependencies 用於支援開發、測試或建置。標記為 private: true 的套件不會被意外發佈。

type 欄位控制 .js 檔案的解譯方式："module" 會選取 ECMAScript 模組；省略該欄位時，則套用預設的 CommonJS 行為。支援兩種模組系統的套件可以使用 exports 欄位公開明確指定的公共進入點。

版本範圍與鎖定檔 #

npm 版本遵循語意化版本規範：major.minor.patch。^5.2.1 這類插入號範圍允許在下一個主要版本發行前進行相容的次要版本與修補程式更新；~5.2.1 這類波浪號範圍只允許修補程式更新。指定精確版本提供最嚴格的限制。

package.json 表示允許的版本範圍，而 package-lock.json 記錄 npm 解析出的確切相依性樹。對於應用程式，應同時提交這兩個檔案，並在持續整合中使用 npm ci。不同於 npm install，npm ci 要求鎖定檔與資訊清單相符，並安裝乾淨且固定的相依性樹。

npm install
npm run test
npm ci
npm outdated
npm update

指令碼與可執行檔 #

npm run <script> 會執行 scripts 欄位中的命令，並將 node_modules/.bin 中的本機可執行檔加入 PATH。因此，不需要全域安裝即可移植地執行 npm run lint。在 -- 後傳遞引數：

npm run test -- --watch

對於偶爾執行的命令，可以使用 npx <package> 或 npm exec <package>。對於貢獻者或 CI 必須重複執行的命令，應優先使用專案相依性和指令碼。

登錄站與發佈 #

公開 npm 登錄站是預設值，但可以在 .npmrc 中為某個範圍選取登錄站：

@acme:registry=https://registry.example.com/

使用在儲存庫外部管理的權杖進行驗證，尤其是在 CI 中。發佈函式庫之前，請檢查 files、.npmignore、exports、授權條款以及產生的 tarball：

npm pack --dry-run
npm publish

函式庫應只發佈預期的執行階段檔案，並記錄支援的 Node.js 版本。應用程式通常保持私有，透過部署而非發佈來交付。