npm ci

定義

npm ci は、npm で package-lock.json（または npm-shrinkwrap.json）に記録された依存ツリーをそのまま再現するインストールコマンドである。
名前は clean install の略で、npm clean-install とも書ける。
CI やコンテナのビルドのように、毎回同じ依存を入れたい自動化の場面で使う。

詳細

npm install との主な違いは次のとおりである。

• lockfile が無いと実行できない
• lockfile と package.json の依存が一致しないと、lockfile を更新せずにエラーで終了する
• node_modules が既にあれば、インストールの前に丸ごと削除する
• package.json と lockfile には一切書き込まない
• プロジェクト全体を一度に入れるだけで、個別のパッケージは追加できない

Dockerfile では package*.json だけを先に COPY してから RUN npm ci を書くと、ソースを変えただけのビルドで依存のレイヤーが再利用される。

よくある誤解

• npm install の速い版: 中身は「lockfile どおりに作り直す」コマンドで、依存を足したり版を上げたりする用途には使えない。
  依存を変えるときは npm install で lockfile を更新してコミットする。
• lockfile のズレを直してくれる: 直さずに止まる。npm ci が package-lock.json と不一致で失敗する はこの挙動である。

関連

再現の土台になる Lockfile と、入れ直される先の node_modules の項目も合わせて読むとよい。