Cannot read properties of null (reading 'matches') エラーの解決方法

npm install 実行時に発生するエラー

npm install 実行時に npm ERR! Cannot read properties of null (reading 'matches') エラーが発生する問題は、主に pnpmとnpmの混在使用 が原因で発生します。このエラーでインストールプロセスが中断された場合、以下の解決方法を試してください。

🔧 主要な解決策

1. node_modulesの削除と再インストール

最も効果的な解決方法は、既存の依存関係を完全にクリーンアップすることです。

# node_modulesディレクトリを削除
rm -rf node_modules

# ロックファイルを削除（存在する場合）
rm -f package-lock.json
rm -f pnpm-lock.yaml

# 正しいパッケージマネージャーで再インストール
pnpm install  # プロジェクトがpnpmを使用している場合
または
npm install   # npmを使用している場合

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

プロジェクトでpnpmとnpmを混在させないことが重要です。初期化時に使用したパッケージマネージャーをインストール時も統一してください。

間違いやすいパターン:

# 誤: pnpm初期化後にnpmを使う
pnpm init
npm install  # ここでエラー発生!

# 正: 同一マネージャーを使用
pnpm init
pnpm install

3. package.jsonでのパッケージマネージャー明示

プロジェクトのpackage.jsonに使用パッケージマネージャーを明記することで、ツール間の競合を防げます。

{
  "packageManager": "pnpm@9.7.1"  // 実際のバージョンを指定
}

バージョン確認方法

pnpm --version  # インストール中のpnpmバージョンを確認

🌐 ネットワーク関連の対策

特定のネットワーク環境では依存関係の解決が失敗する場合があります。

# キャッシュクリア
npm cache clean --force
pnpm store prune

# レジストリ変更例（中国など制限がある地域向け）
npm config set registry https://registry.npmmirror.com

ネットワークアダプタの問題

Wi-Fi環境で発生する場合は、以下を試してください：

• モバイルテザリングへの切り替え
• VPNの使用停止
• 別のネットワークインターフェースの利用

💡 エラーの根本原因

Cannot read properties of null エラーの本質は、pnpmで作成された依存関係ツリーをnpmが正しく解析できないことにあります。pnpmは依存関係をnode_modulesに仮想ストアとして管理するため、npmとの互換性問題が発生します。

主な発生シナリオ：

1. pnpm install でプロジェクトを初期化後 npm install を実行
2. pnpmプロジェクトで誤ってnpmコマンドを使用
3. ツールチェイン(pnpm)と手動操作(npm)の混合

✅ ベストプラクティス

1. プロジェクトごとにパッケージマネージャーを統一
2. チーム開発では.npmrcでエンジンバージョンを固定
3. CI/CD環境ではpackageManagerフィールドを活用

{
  "packageManager": "pnpm@9.7.1"
}

初期化時に使用したパッケージマネージャーを一貫して使用することで、このエラーを95%以上予防できます。プロジェクト参加時にはpackage.jsonのpackageManager設定を必ず確認しましょう！