npm ci が package-lock.json と不一致で失敗する

npm ci は package.json と package-lock.json が完全に一致していることを前提とし、ズレると EUSAGE エラーで即停止する。
手元で npm install を実行して lockfile を更新し commit するのが正攻法。

#npm #npm-ci #package-lock #lockfile #ci

公開: 2026-06-11更新: 2026-08-29

実行例あり（2026-08-29 に実環境で検証）

要約

npm error code EUSAGE とともに npm ci can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync が出るのは、package.json と package-lock.json がズレている状態。npm ci は lockfile を一切更新しない設計なので、npm install のように自動で辻褄を合わせず即エラーで止まる。

実行例

lockfile に載っていない依存を package.json 側にだけ足した状態で npm ci を走らせると、npm 10.8.2 は EUSAGE で止まり、不足しているパッケージ名を Missing: left-pad@1.3.0 from lock file の形で名指しする。npm install で lockfile を更新したあとは、同じ npm ci がそのまま成功する。

セットアップ: 依存なしの package.json と package-lock.json を作成した

$ npm ci
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: left-pad@1.3.0 from lock file
npm error
npm error Clean install a project
npm error
npm error Usage:
npm error npm ci
npm error
npm error Options:
npm error [--install-strategy <hoisted|nested|shallow|linked>] [--legacy-bundling]
npm error [--global-style] [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
npm error [--include <prod|dev|optional|peer> [--include <prod|dev|optional|peer> ...]]
npm error [--strict-peer-deps] [--foreground-scripts] [--ignore-scripts] [--no-audit]
npm error [--no-bin-links] [--no-fund] [--dry-run]
npm error [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
npm error [-ws|--workspaces] [--include-workspace-root] [--install-links]
npm error
npm error aliases: clean-install, ic, install-clean, isntall-clean
npm error
npm error Run "npm help ci" for more info
npm error A complete log of this run can be found in: /root/.npm/_logs/2026-08-29T01_43_57_944Z-debug-0.log
終了コード: 1

$ npm install
npm warn deprecated left-pad@1.3.0: use String.prototype.padStart()
 
added 1 package, and audited 2 packages in 366ms
 
found 0 vulnerabilities
終了コード: 0

$ npm ls left-pad
tmp.3gcn1bhyq8@1.0.0 /tmp/tmp.3GCN1BHyq8
`-- left-pad@1.3.0

$ npm ci
npm warn deprecated left-pad@1.3.0: use String.prototype.padStart()
 
added 1 package, and audited 2 packages in 353ms
 
found 0 vulnerabilities
終了コード: 0

$ npm -v
10.8.2

— 2026-08-29 時点の出力

検証環境

検証日

2026-08-29

実行環境

node:20Debian GNU/Linux 12 (bookworm)

バージョン

Node.js 20.20.2
npm 10.8.2
Python 3.11.2
Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

lockfile 未更新: package.json の依存を書き換えたが npm install をしておらず、package-lock.json が古いまま。
lockfile の手編集・マージ事故: package-lock.json を手で触った、あるいはコンフリクトを雑に解決して不整合が残った。
同期漏れのコミット: 他のメンバーが依存を足したのに lockfile を commit し忘れている。
lockfileVersion 差: npm 6 と 9 以降など世代差で lockfileVersion が変わり、整合チェックに引っかかる。

解決策

1. lockfile を更新して commit する

npm install
git add package-lock.json
git commit -m "chore: sync package-lock.json"

npm-ci のドキュメント（新しいタブで開く）にあるとおり、npm ci は lockfile が package.json と一致しなければエラー終了する。
lockfile を書き換えられるのは npm install 側だけ。

2. 不一致パッケージを特定する

npm error Invalid: lock file's left-pad@1.3.0 does not satisfy left-pad@1.4.0

エラー本文に食い違っているパッケージ名と版が出るので、確認してから意図した版に揃える。

3. npm バージョンを CI と揃える

ローカルと CI（setup-node の node-version 指定など）で npm のメジャーバージョンを合わせると lockfileVersion の食い違いを防げる。npm -v で双方を確認する。

4. 壊れた lockfile を作り直す

rm package-lock.json
npm install
git diff package-lock.json

どうしても直らないときは再生成し、差分に意図しないバージョン上げが無いかレビューしてから commit する。

要約

実行例