npm ciとnpm installの違い|ロックファイル・キャッシュ・エラー対処

公開 更新 約4分で読む著者:admin

依存関係を追加・更新するならnpm install、記録済みの構成をクリーンに入れ直すならnpm ciが基本的な使い分けです。ただし、npm installが毎回ロックファイルを無視して最新版を選ぶわけではありません。

更新:2026年10月26日。ロックファイルの扱い、オフライン指定、キャッシュ、セキュリティ上の限界を訂正しました。npm 11の公式資料を参照しています。

まず違いを表で確認

項目npm installnpm ci
ロックファイルあれば利用する。依存指定との整合性によって更新する。package-lock.jsonまたはnpm-shrinkwrap.jsonが必要。
package.jsonと不整合依存を解決し、必要に応じてロックを更新する。エラーで停止する。
node_modules現在の状態を踏まえてインストールする。既存のものを削除して入れ直す。
個別パッケージの追加可能。不可。プロジェクト全体が対象。
マニフェスト・ロックの書き換え操作内容に応じて変更する。変更しない。

これらの挙動はnpm ciとnpm installの公式資料に対応しています。速度は通信、キャッシュ、依存パッケージのビルドなどに左右されるため、ciが必ず速いという意味ではありません。

チーム開発の基本フロー

開発者
npm installで依存を変更
レビュー
package.jsonとロックの差分を確認
CI・他の開発者
npm ciで構成を再現
図1:依存を決める作業と、決まった依存を入れる作業を分ける。
BASH
# 初回の依存解決、または意図した変更を反映する
npm install

# 差分を確認し、必要な変更だけコミットする
git diff -- package.json package-lock.json

# ロックファイルがそろったプロジェクトで実行する
npm ci

# 本番実行に開発依存が不要な構成の場合
npm ci --omit=dev

--omit=devはビルド前に付けてよいとは限りません。TypeScriptのコンパイラーやビルドツールをdevDependenciesに置いている場合、ビルド段階では必要になります。また、npm ciはローカル開発でも利用できます。

キャッシュとオフライン指定の違い

BASH
npm config get cache
npm ci --prefer-offline
npm ci --offline

--prefer-offlineはキャッシュの鮮度確認を省く設定で、不足するデータはネットワークから取得します。--offlineはnpm自身のネットワーク要求を行わず、不足していれば失敗します。ただし、インストール時に実行されるパッケージのスクリプトまでOSレベルで通信遮断する指定ではありません。定義はnpmの設定リファレンスで確認できます。

CIでnpm ciを使うときは、毎回削除されるnode_modulesをキャッシュするより、npmのダウンロードキャッシュを利用する構成をまず検討します。キャッシュキーにはOS、ロックファイル、必要に応じてNode.jsのバージョンを含めます。

エラーが出たら何を確認する?

状況確認と対応
ロックファイルがない正しい作業フォルダーか確認。初回なら開発環境でnpm installを実行し、生成結果をレビューする。
依存指定とロックが不整合意図した変更か確認して同期する。CI側だけでロックを作り直して隠さない。
peer dependencyなどの不一致Node.js・npmのバージョンと.npmrcを比較する。
オフラインで失敗必要なパッケージがキャッシュにあるか確認する。
ネイティブ依存のビルド失敗OS、CPU、コンパイラー、対応Node.jsの条件を確認する。

ロック生成時に--legacy-peer-depsなど依存ツリーに影響する指定を使った場合は、CI側にも同じ条件が必要になることがあります。エラーを見ずにフラグを足すのではなく、プロジェクトの設定として必要な理由を確認してください。

再現性は、安全性の保証ではない

ロック済みの依存にも脆弱性や不適切な処理が含まれる可能性があります。npm ciは既知の構成へ戻す手段であり、マルウェア検査やセキュリティ更新の代わりではありません。依存の出所、変更差分、公開された注意情報、インストール時スクリプトの必要性を確認します。

同じロックファイルでも、OSやCPU、オプション依存、ネイティブビルド、環境変数などによって結果は変わり得ます。チームではNode.jsとnpmのバージョンも記録し、インストール後のテストまでを再現性の確認に含めます。

関連:Express 5でAPIを作る/Dockerとvenvの分離範囲。

\ 最新情報をチェック /

記事一覧に戻る

コメントを書く

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です