できない.dev

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

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

公開: 更新:

症状できない · exit 1
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
解決後できた · exit 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

2026-08-29 に node:20(npm 10.8.2 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

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 が出る。
EUSAGE が出るのは、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
$ echo $?
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
$ echo $?
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
$ echo $?
0
$ npm -v
10.8.2

— 2026-08-29 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-08-29 検証(ほか 1 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

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

解決策

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 する。

よくある原因

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