意外と忘れがちなnpm ci 完全ガイド - 知っておくべき使い方と注意点【備忘録】
adminnpm ci とは何か
npm ci は「Clean Install」の略で、npm 5.7.0 で導入されたパッケージインストールコマンドです。従来の npm install と似ていますが、CI/CD環境での使用を想定して設計されており、より高速で信頼性の高いインストールを実現します。
npm install との違い
主な特徴
npm ci の動作:
package-lock.jsonの内容を厳密に再現node_modulesを削除してからクリーンインストールpackage.jsonとpackage-lock.jsonの整合性をチェックpackage-lock.jsonやpackage.jsonを更新しない- 個別パッケージのインストールは不可
npm install の動作:
package.jsonの範囲指定に基づいて最新版を解決- 既存の
node_modulesがある場合は差分インストール package-lock.jsonを自動更新する可能性がある- 個別パッケージのインストールが可能
いつ使うべきか
CI/CD環境では npm ci を使う
継続的インテグレーション環境では npm ci の使用が推奨されます。理由は以下の通りです:
- 再現性: ロックファイルに記載された正確なバージョンでインストール
- 速度: クリーンインストールのため、キャッシュが効きやすく高速
- 信頼性: 予期しないバージョン変更を防止
ローカル開発では npm install が便利
開発環境では通常 npm install を使用します:
- 新しいパッケージの追加が簡単
- 既存の
node_modulesを活用できる - 依存関係の更新が柔軟
実践的な使用例
基本的な使い方
# 通常のインストール
npm ci
# より詳細なログ出力
npm ci --loglevel verbose
# 開発依存関係を除外
npm ci --production
GitHub Actions での使用例
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
GitLab CI での使用例
install:
script:
- npm ci
cache:
paths:
- node_modules/
よくあるエラーと対処法
package-lock.json がない場合
npm ERR! The package-lock.json file was created with an old version of npm
この場合は npm install を実行して package-lock.json を生成してからコミットしましょう。
整合性エラー
npm ERR! cipm can only install packages when your package.json and package-lock.json are in sync
package.json と package-lock.json の内容が一致していません。npm install を実行して同期させてください。
パフォーマンスの最適化
キャッシュの活用
CI環境では npm のキャッシュを活用することで、さらに高速化できます:
# キャッシュディレクトリの確認
npm config get cache
# GitHub Actions でのキャッシュ例
- uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
オフラインインストール
パッケージが既にキャッシュされている場合、オフラインモードでさらに高速化:
npm ci --prefer-offline
セキュリティ上の利点
npm ci はロックファイルを厳密に守るため、意図しないバージョンアップによる脆弱性の混入を防ぎます。また、常にクリーンな状態からインストールするため、汚染された node_modules による問題も回避できます。
まとめ
- CI/CD環境: 必ず
npm ciを使用 - ローカル開発: 通常は
npm installを使用 - メリット: 高速、信頼性、再現性
- 注意点:
package-lock.jsonが必須、個別インストール不可
npm ci を適切に使い分けることで、より安定した開発ワークフローを構築できます。特にチーム開発やCI/CD環境では、その恩恵を最大限に享受できるでしょう。
＼ 最新情報をチェック ／
