テクノロジー · 実用ガイド
npm ci が package-lock の不一致を示すとき：再生成の前に manifest・設定・npm 版を監査する
失敗時の入力を先に保存します。同じ EUSAGE でも、依存関係のずれ、プロジェクト設定、古い lockfile、npm 版固有の resolver が原因になり得ます。
npm ci が package.json と package-lock.json の不一致を報告するのは、固定されるべき依存ツリーの書き換えを拒否しているためです。これは整合性ゲートの失敗であり、原因が一つとは限りません。失敗時の入力を保存し、どれが変わったかを証明してから manifest、設定、npm 版、lockfile のどれを直すか決めます。
最初に package-lock.json を削除したり、CI を npm install に切り替えたり、--force を追加してはいけません。比較材料が失われ、小さな変更が大きなツリー変更に広がる可能性があります。安全な修正は Missing または Invalid の項目を説明し、想定ポリシーで再現でき、lockfile 差分をレビュー可能にします。
1. EUSAGE を整合性ゲートとして読む
npm ci は自動化された再現可能なインストール向けです。lockfile を要求し、既存の node_modules を削除してからインストールし、package.json や lockfile を書き換えません。不一致なら終了し、未レビューの依存変更が CI に入るのを防ぎます。
別のコマンドを試す前にエラー全文を保存します。Missing や Invalid の各行、作業ディレクトリ、repository root と workspace のどちらで実行したかを残します。最初の package 名と範囲は分岐の手掛かりですが、末尾の npm install 案内だけで再生成が唯一の修正とは言えません。
2. manifest・lockfile・環境の読み取り専用台帳を作る
正確な commit と package.json／package-lock.json の変更状態を記録します。dependencies、devDependencies、optionalDependencies、peerDependencies、bundledDependencies、overrides、workspaces を確認します。lockfileVersion、packages[""]、エラーで示された package path を読み、生成された integrity や依存フィールドは手編集しません。
node --version、npm --version、プロジェクト .npmrc、関連環境変数、正確な CI コマンドを記録します。legacy-peer-deps、strict-peer-deps、install-links、omit/include、workspace selector を含め、registry token や資格情報は必ず伏せます。
3. 意図した manifest 変更と誤編集を分ける
package.json が lockfile より後に変わったなら、その依存変更が意図されレビュー済みか判断します。直接依存を追加したのに packages[""].dependencies に無い場合は manifest drift です。overrides、workspace membership、package-manager 設定も通常の dependencies が同じままツリーを変えます。
意図した変更なら、指定 npm 版と設定を使う管理された開発環境で lockfile を再生成します。誤編集ならレビュー済み manifest を復元します。CI に毎回ツリーを修復させず、生成 lockfile を明示的な source change としてレビューします。
4. lockfile 作成時の install policy を再現する
公式 npm ci ガイドは、ツリー形成 flag で作成した lockfile には同じ flag が必要だと説明します。legacy-peer-deps が代表例です。全開発者と CI が必要とする設定は project .npmrc に commit し、個人設定で repository tree を暗黙に決めないようにします。
同じ npm major、project .npmrc、workspace command で clean checkout を比較します。flag を足した時だけ成功するなら、その flag が repository policy である理由を説明してから commit します。記録のない成功コマンドは問題を別の machine に移しただけかもしれません。
5. npm 版の挙動と壊れた lockfile を区別する
manifest、lockfile、設定が同じで npm 版により結果が変わるなら、書き換え前に小さな version matrix を再現します。サポート版と隣接版の完全なエラーを保存します。最近の upstream 事例のように npm install 後でも npm ci が拒否する resolver path は、gate を無視する理由ではなく escalation の証拠です。
本当に壊れた／古い lockfile には parse failure、root metadata 欠落、不可能な package map、conflict marker、既知の format transition など具体的証拠が必要です。元ファイルを保存し、想定 toolchain で一度だけ再生成し全差分を確認します。
6. clean checkout で最小修正を検証する
証拠に基づく最小修正後、clean checkout から開始します。想定 Node/npm 版と commit 済み設定だけを使い、CI と同じ npm ci を実行します。lockfile が変わらないこと、正しい workspace、lifecycle script、既存 test／build を確認します。
lockfile 差分は依存コードとしてレビューします。root range、resolved version、integrity、peer relationship、削除が意図した変更に対応すべきです。再失敗したら新しいエラーを保存して台帳の分岐に戻り、偶然通るまで再生成を繰り返しません。
