依存関係を追加・更新するならnpm install、記録済みの構成をクリーンに入れ直すならnpm ciが基本的な使い分けです。ただし、npm installが毎回ロックファイルを無視して最新版を選ぶわけではありません。
更新:2026年10月26日。ロックファイルの扱い、オフライン指定、キャッシュ、セキュリティ上の限界を訂正しました。npm 11の公式資料を参照しています。
まず違いを表で確認
| 項目 | npm install | npm ci |
|---|---|---|
| ロックファイル | あれば利用する。依存指定との整合性によって更新する。 | package-lock.jsonまたはnpm-shrinkwrap.jsonが必要。 |
| package.jsonと不整合 | 依存を解決し、必要に応じてロックを更新する。 | エラーで停止する。 |
| node_modules | 現在の状態を踏まえてインストールする。 | 既存のものを削除して入れ直す。 |
| 個別パッケージの追加 | 可能。 | 不可。プロジェクト全体が対象。 |
| マニフェスト・ロックの書き換え | 操作内容に応じて変更する。 | 変更しない。 |
これらの挙動はnpm ciとnpm installの公式資料に対応しています。速度は通信、キャッシュ、依存パッケージのビルドなどに左右されるため、ciが必ず速いという意味ではありません。
チーム開発の基本フロー
npm installで依存を変更
package.jsonとロックの差分を確認
npm ciで構成を再現
--omit=devはビルド前に付けてよいとは限りません。TypeScriptのコンパイラーやビルドツールをdevDependenciesに置いている場合、ビルド段階では必要になります。また、npm ciはローカル開発でも利用できます。
キャッシュとオフライン指定の違い
--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のバージョンも記録し、インストール後のテストまでを再現性の確認に含めます。