科技 · 實用指南
npm ci 顯示 package-lock 不同步？先稽核清單、安裝參數與 npm 版本，再決定是否重建
先保留失敗時的輸入。同一個 EUSAGE 訊息可能源自相依套件漂移、專案設定差異、舊鎖定檔或特定 npm 解析器行為。
當 npm ci 回報 package.json 與 package-lock.json 不同步時，它拒絕改寫本應凍結的相依樹。這個訊息表示一致性檢查失敗，而非單一根因。安全做法是先保留失敗輸入、證明哪一項改變，再判斷應修正清單、專案設定、npm 版本或產生的鎖定檔。
不要先刪除 package-lock.json、把 CI 改成 npm install，或加入 --force。這會抹去解釋失敗所需的比較，也可能把小型預期修改放大成大量相依樹變動。好的修復要能解釋具體 Missing 或 Invalid 項目、在預期安裝策略下重現，並留下可審查的鎖定檔差異。
1. 把 EUSAGE 訊息視為一致性閘門
npm ci 用於自動化且可重現的安裝。它需要鎖定檔，安裝前移除既有 node_modules，且不寫入 package.json 或鎖定檔。清單與鎖定檔不一致時會退出，避免 CI 靜默接受未審查的新相依樹。
嘗試其他命令前先複製完整錯誤。保留每一行 Missing 或 Invalid、工作目錄，以及命令是在倉庫根目錄或 workspace 執行。第一個具名套件和版本範圍通常決定分支；最後的通用 npm install 建議不代表重建是唯一正確修復。
2. 建立唯讀清單、鎖定檔與環境台帳
記錄精確 commit，確認 package.json 或 package-lock.json 是否有未提交修改。檢查 dependencies、devDependencies、optionalDependencies、peerDependencies、bundledDependencies、overrides 與 workspaces。鎖定檔要記下 lockfileVersion，並檢查 packages[""] 根節點與錯誤點名路徑；不要手改產生的 integrity 或相依欄位。
記錄 node --version、npm --version、專案 .npmrc、相關環境變數與完整 CI 命令。納入 legacy-peer-deps、strict-peer-deps、install-links、omit/include 與 workspace 選擇器。登錄檔權杖和憑證必須遮蔽；這是比較台帳，不是秘密傾印。
3. 分開預期清單漂移與意外編輯
package.json 若晚於鎖定檔改變，先判斷相依編輯是否有意且已審查。新增直接相依但 packages[""].dependencies 沒有對應項，是清單漂移；overrides、workspace 成員或套件管理設定也可能在一般 dependencies 未變時改變解析樹。
預期修改應在受控開發環境，以指定 npm 版本與設定重建；意外修改則還原已審查清單。不要讓 CI 每次修樹：提交產生的鎖定檔是原始碼變更，需要明確差異與責任審查。
4. 重現產生鎖定檔時的安裝策略
官方 npm ci 指南提醒，用樹形參數產生的鎖定檔必須以相同參數安裝，legacy-peer-deps 是常見例子。所有開發者與 CI 都需要的設定應提交到專案 .npmrc；個人設定不應暗中決定倉庫相依樹。
以相同 npm 主版本、專案 .npmrc 與 workspace 命令比較乾淨簽出。若環境只有加旗標才通過，先說明該旗標為何是倉庫策略再提交。沒有紀錄的成功命令可能只把問題移到另一台機器。
5. 區分 npm 版本行為與損壞鎖定檔
清單、鎖定檔和設定相同，但失敗隨 npm 版本變化時，先建立小型版本矩陣。保存支援版本與相鄰版本的錯誤。近期上游案例顯示特定解析路徑可能 npm install 成功、npm ci 仍拒絕；這是升級通報證據，不是繞過閘門的理由。
真正損壞或過時的鎖定檔需要具體證據，例如解析失敗、根中繼資料遺失、不可能的套件映射、衝突標記或已知格式轉換。保留原檔，以預期工具鏈重建一次並比較全部差異；大量無關變動表示環境仍未受控。
6. 從乾淨簽出驗證最小修復
做出最小且有證據的修正後，從乾淨簽出開始。使用預期 Node/npm 版本，只載入已提交設定並執行與 CI 相同的 npm ci。確認鎖定檔不再變更、正確 workspace 已安裝、生命週期腳本符合預期，且原有測試或建置通過。
把鎖定檔差異當作相依程式碼審查：根範圍、解析版本、integrity、peer 關係與移除項都要符合預期。再次失敗就保存新錯誤並回到分支台帳，不要反覆重建到偶然通過。
