package.json 怎麼看才有用？用一個能啟動、測試與重建的 Node.js 專案練習交接

專題編輯：Derek Chou｜AI 技術與架構編輯 · 文件核對 2026.11.09

接手一個專案，先找出三個可執行的承諾

假設同事交來一個由 AI 協助開發的報價功能，畫面可以開，README 卻只寫「安裝後執行」。資訊人員最先要確認的不是使用哪個 AI 模型，而是：安裝依賴的依據在哪裡、服務由哪個指令啟動，以及出錯時哪項測試會攔住變更。這是示範情境，不是特定企業的實際案例。

package.json 是上述資訊的入口。它可以描述套件名稱、版本、scripts、依賴與環境條件；其中 scripts 是命令的名稱對照表，檔案本身不會替團隊補上伺服器或測試。例如 "start": "node src/server.js" 的承諾，必須由真正存在且可執行的 src/server.js 履行。npm package.json 文件

先用下表做交接判斷，能把「缺文件」和「程式壞了」分開處理：

若還分不清 Runtime 與應用程式的關係，可先讀執行環境與 Runtime 指南。本文的範圍則是把 npm 專案契約變成可重跑的檢查。

本次練習的環境、成果與限制

範例是只監聽 127.0.0.1 的 Node.js API，不含第三方套件、資料庫、帳號與真實客戶資料。金額以正整數新臺幣表示；超過 100,000 元回傳需要額外檢查。這個門檻只是測試規則，不能直接當成公司的授信或報價政策。

2026 年 11 月 9 日，本機驗證使用 macOS、Node.js 22.23.4、npm 10.9.9。這是一個可追溯的測試版本，並非「最新版本」推薦；企業應以Node.js 官方維護狀態及自己的相容性測試安排升級。這次結果不等於所有 Node 22 更新版或其他作業系統都通過。

下載本篇完整範例專案後解壓，進入含 package.json 的目錄。檔案包括 .nvmrc、package-lock.json、src/quote.js、src/server.js、test/quote.test.js 及 scripts/verify-gate.js；後兩者分別執行業務邊界測試與負例驗證。

步驟一：閱讀 scripts，再確認每個目標檔案

範例的核心設定如下：

{
  "name": "tdr-quote-contract-demo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "test": "node --test test/*.test.js",
    "verify:gate": "node scripts/verify-gate.js"
  },
  "engines": { "node": ">=22 <23" },
  "dependencies": {},
  "devDependencies": {}
}

在終端機執行：

node --version
npm --version
npm run

預期看到 Node 的版本號、npm 的版本號，以及 start、test、verify:gate 三個腳本。若 npm 回報找不到 package.json，先確認目前目錄；若啟動時出現模組不存在，核對 scripts 的路徑和檔案大小寫，別先把問題歸咎於套件下載。

這裡的 private: true 用於防止誤把專案發布為 npm 套件，不會為 API 加上登入或防火牆。engines 表達預期版本範圍，一般 npm 設定下不能把它當成必然強制執行的版本鎖；本範例另以 .nvmrc 記錄精確版本。type: module 則讓這組 .js 檔使用 ECMAScript modules 的 import/export 寫法。

步驟二：以鎖版檔重建，而不是重新猜一次依賴

完整專案已附上鎖版檔，因此直接執行：

npm ci --ignore-scripts --no-audit --no-fund

範例沒有第三方依賴，成功時不會多出一長串套件。--ignore-scripts 在這個練習中避免安裝生命週期腳本；它不會替代後面明確執行的 npm test。--no-audit 表示這次命令沒有做漏洞稽核，不能把安裝成功寫成安全掃描通過。

npm ci 要求已有 lockfile；當依賴宣告與鎖版資訊不一致時，它應失敗，而不在安裝過程偷偷改寫兩份檔案。新增或升級依賴時，應在開發分支使用適當的 install/update 流程，檢視 package.json 與 lockfile 差異，再交給 CI 乾淨重建。npm ci 文件

若下載後漏掉 lockfile，先回到交付來源補齊；不要為了讓驗收變綠，就把驗收命令改成 npm install。本次另外在可丟棄的副本移除 lockfile，確認 npm ci 會以非零結束碼拒絕執行；原始專案沒有被改動。

步驟三：測試要能區分邊界兩側

src/quote.js 的業務函式很短：

export function reviewAmount(amount) {
  if (!Number.isSafeInteger(amount) || amount <= 0) {
    throw new TypeError('amount must be a positive safe integer in TWD');
  }
  return { amount, reviewRequired: amount > 100000 };
}

執行 npm test。這份範例明確指定測試檔案，而非只讓一個印出「OK」的腳本充當測試。本機結果為 5 個測試通過，涵蓋 50,000 元、恰好 100,000 元、100,001 元，以及零、負數、小數、非數值與不安全整數的拒絕行為。Node.js 測試執行器文件

接著執行：

npm run verify:gate

這個工具會建立臨時副本，把 > 故意改成 >=，再跑同一組測試。因為 100,000 元的預期結果被破壞，測試執行器必須失敗；驗證工具看到這個預期失敗，才回報負例檢查通過，最後清除副本。若改壞後仍全綠，就代表測試沒有保護這個邊界。

「正常測試通過」和「已確認測試能抓到錯誤」是不同證據。它們都不能證明沒有任何漏洞，但能直接改善只檢查指令有沒有執行的交接方式。

步驟四：啟動 API，檢查回應後結束練習

第一個終端機執行 npm start；另一個終端機執行：

curl --fail http://127.0.0.1:3000/health
curl --fail 'http://127.0.0.1:3000/quote?amount=100001'
curl -i 'http://127.0.0.1:3000/quote?amount=-1'

預期依序得到狀態 ok、reviewRequired: true，以及 HTTP 400。測試完在啟動服務的終端機按 Ctrl+C。若連線被拒絕，確認服務仍在執行；若埠號被占用，在 macOS/Linux 可改用 PORT=3001 npm start，並同步修改檢查 URL。不要為了方便連線就把監聽位址改成公開網路。

這個練習驗證的是本機範例，不含 TLS、身份驗證、授權、速率限制或監控。真實金額還需確認幣別、精度與業務規則；對外服務不能原樣搬上正式環境。

有了 package.json，還有哪些事沒有被解決？

當專案開始加入第三方套件，應把「執行時需要」和「建置、測試時需要」的依賴分開。是否只安裝 production dependencies，要看建置發生在哪個階段，而不是認為 devDependencies 永遠可以刪掉。使用原生模組時，作業系統與 CPU 架構也可能影響重建結果。

供應鏈審查則需回答套件從哪裡來、誰維護、授權義務為何，以及已知漏洞是否真的觸及此系統。不要因 npm registry 可下載就推定授權無條件，也不要不看破壞性變更就套用強制升級。這些是團隊的風險判斷，lockfile 只提供依賴追溯的一部分。

交付時保留四種資料就能開始：版本紀錄、lockfile、測試輸出、啟動端點結果。README 每寫一個命令，都應對得上實際腳本；若專案需要環境變數，提供沒有秘密的範例欄位與缺值錯誤，不把真實 API Key 塞進 scripts。

常見問題

只要 npm ci 成功，就代表可以部署嗎？ 還不夠。它只處理依賴安裝這個環節；程式測試、設定、資料庫遷移與部署驗收各有自己的證據。

這份範例為什麼沒有 build？ 因為示範使用可直接由 Node 執行的 JavaScript，沒有需要編譯的步驟。實際使用 TypeScript 或前端框架時，再增加相應建置腳本與測試，不為了湊清單新增空指令。

固定版本後是不是不用升級？ 固定版本方便重現，升級政策負責維護安全與相容性。兩者應配合：在分支更新版本、重跑測試，再讓版本紀錄跟著改變。

來源與實測邊界

本篇以 npm 的 package.json 與 npm ci 文件、Node.js 測試執行器及官方維護版本表查核工具行為；範例程式與負例測試為原創教學。此頁不提供網站正式部署與商業成效保證。

圖片與素材說明：封面為使用者提供的原創概念圖，原封包標示由 AI 生成與編排，並非操作截圖。本文由 AI 協助修訂與查核，未宣稱具名人工審核；Derek Chou 為 TARAISG AI 編輯計畫的專題角色。

內容提供：TARAISG。本文由 AI 協助整理與查核；專題編輯為天地人 AI 編輯計畫的策展角色，未宣稱經具名人工或專家審核。