NXビルドエラー「Cannot find module '@nx/nx-linux-x64-gnu'」の解決法

問題の概要

GitHub ActionsなどのCI環境でNXを使用してAngularプロジェクトをビルドする際、以下のエラーが発生する場合があります：

Error: Cannot find module '@nx/nx-linux-x64-gnu'

このエラーはNXがプラットフォーム固有のネイティブバイナリを見つけられない場合に発生します。主な原因は：

• オプション依存関係（optionalDependencies）が正しくインストールされていない
• package-lock.jsonの破損や古いキャッシュの影響
• CI環境でのnpmインストール設定の問題

NX公式ドキュメントでも説明されている通り、プラットフォーム対応バイナリはオプション依存関係として提供されますが、CI環境ではこれらの依存関係が正しく解決されないケースがあります。

効果的な解決策

⚙️ 方法1: npmインストールオプションの追加（推奨）

最も確実な解決法は、package.jsonに明示的に依存関係を定義し、CIで--include=optionalフラグを使用することです。

1. package.jsonに利用中のNXバージョンに対応するプラットフォームバイナリを追加：

{
  "optionalDependencies": {
    "@nx/nx-darwin-arm64": "18.0.4",
    "@nx/nx-darwin-x64": "18.0.4",
    "@nx/nx-linux-x64-gnu": "18.0.4",
    "@nx/nx-win32-x64-msvc": "18.0.4"
  }
}

2. CIスクリプトでnpmコマンド実行時にフラグを追加：

# GitHub Actionsの例
- name: 依存関係インストール
  run: npm ci --include=optional  # または npm install --include=optional

🔄 方法2: 依存関係ファイルのリセット

ロックファイルの不整合が原因の場合は、キャッシュを含む完全なリセットが有効です：

# node_modulesとロックファイルを削除
rm -rf node_modules
rm package-lock.json

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

# 依存関係の再インストール
npm install

⏪ 方法3: npm v6による再生成（レガシー対応）

古いnpmバージョンが影響する場合は、一時的なダウングレードが有効です：

npm install -g npm@6     # npm v6にダウングレード
rm -rf node_modules      # 既存モジュール削除
rm package-lock.json     # ロックファイル削除
npm install              # 依存関係再インストール
npm install -g npm@10    # npm最新版に戻す
npm install              # ロックファイル最新化

🔍 各解決策のポイント比較

方法	適用ケース	メリット	注意点
--include=optional	全CI環境	根本解決・再発防止	package.json編集が必要
ファイルリセット	キャッシュ起因	シンプル・即時対応	毎回実行が必要
npmダウングレード	npmバージョン問題	特定環境で有効	一時的な回避策

💡 予防策とベストプラクティス

1. CIキャッシュ戦略の最適化
   GitHub Actionsではactions/cacheを使用する際、キャッシュキーにpackage-lock.jsonのハッシュを含めると効果的です

2. バージョン固定の重要性
   インストールエラー防止のため、package.jsonで正確なNXバージョンを指定してください

3. 定期的な依存関係更新
   古い依存関係はエラーの原因になるため、npm outdatedで確認後、安全にアップデート

---

参考リソース:

• NX公式トラブルシューティングガイド
• npmオプション依存関係の仕様: npm公式ドキュメント