npm ci エラー：package-lock.json が見つからない場合の解決方法

GitHub Actions などのCI環境で npm ci コマンドを実行した際に、以下のエラーが発生することがあります：

npm ERR! cipm can only install packages with an existing package-lock.json or npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or later to generate it, then try again.

この記事では、このエラーの原因と効果的な解決方法について詳しく説明します。

問題の原因

npm ci コマンドは、package-lock.json または npm-shrinkwrap.json ファイルが存在し、有効な形式であることを前提としています。このエラーが発生する主な原因は以下の通りです：

• package-lock.json ファイルが存在しない
• package-lock.json と package.json の内容が同期していない
• 異なるNode.jsバージョンやパッケージマネージャー間での互換性問題
• グローバルなnpm設定による影響

解決方法

1. package-lock.json を生成する

package-lock.json が存在しない場合、まず生成する必要があります：

npm install --package-lock-only

このコマンドは node_modules をインストールせずに、package.json に基づいて package-lock.json のみを生成します。

2. 依存関係の完全な再同期

最も確実な方法は、依存関係を完全に再構築することです：

# node_modules と package-lock.json を削除
rm -rf node_modules package-lock.json

# npmキャッシュのクリア
npm cache clean --force

# 新しい依存関係のインストール
npm install

変更内容をコミットしてリポジトリにプッシュしてください。

3. Node.jsバージョンの統一

開発環境とCI環境でNode.jsのバージョンが異なると、互換性問題が発生することがあります：

// package.json
{
  "engines": {
    "node": "18.20.2",
    "npm": "10.5.0"
  }
}

TIP

CI環境で使用しているNode.jsのバージョンをローカル環境にもインストールし、nvmなどのバージョン管理ツールを使用して切り替えることを推奨します。

4. パッケージマネージャーの統一

YarnやPNPMを使用している場合、CI環境でも対応するコマンドを使用する必要があります：

Yarnを使用する場合：

# GitHub Actionsの例
- name: Install dependencies
  run: yarn install --frozen-lockfile

PNPMを使用する場合：

# GitHub Actionsの例
- name: Install Node.js dependencies
  run: |
    npm i -g pnpm
    pnpm i

5. 複数パッケージマネージャー対応のスクリプト

プロジェクトによって使用するパッケージマネージャーが異なる場合、以下のような条件分岐スクリプトが有効です：

if [ -e yarn.lock ]; then
  yarn install --frozen-lockfile
elif [ -e package-lock.json ]; then
  npm ci
else
  npm i
fi

6. グローバルnpm設定の確認

legacy-peer-deps などのグローバル設定が package-lock.json に影響を与えることがあります：

# 問題のある設定をリセット
npm config delete legacy-peer-deps

7. package-lock.jsonの整合性確認

JSON構文エラーやマージコンフリクトによる破損がないか確認してください：

# JSON構文の検証
node -e "require('./package-lock.json')" && echo "Valid JSON"

ケース別対応

AWS Amplifyでの問題

AWS Amplifyでこの問題が発生した場合、ビルド設定を変更します：

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm install --package-lock-only  # package.jsonとpackage-lock.jsonを同期
        - npm ci
    build:
      commands:
        - npm run build

Firebase Functionsでの問題

Firebaseデプロイ時に問題が発生する場合：

# package-lock.jsonを削除してデプロイ
rm package-lock.json
firebase deploy --only functions

WARNING

この方法は一時的な解決策であり、依存関係のバージョン管理ができなくなるため、長期的には推奨されません。

予防策

1. 一貫した環境管理：開発環境とCI環境で同じNode.jsバージョンを使用する
2. パッケージマネージャーの統一：プロジェクト内で一つのパッケージマネージャーを使用する
3. 定期的な依存関係の更新：npm audit と npm update を定期的に実行する
4. CIスクリプトのテスト：主要な変更前にCIパイプラインをローカルでテストする

まとめ

npm ci エラーの根本的な原因は、依存関係の管理不一致にあります。適切な package-lock.json ファイルを維持し、環境間の一貫性を保つことで、この問題を効果的に解決できます。CI/CDパイプラインの信頼性を高めるには、これらのベストプラクティスを継続的に適用することが重要です。