npm installエラー大全：全エラーの原因と解決方法

npm install を実行して赤いエラーメッセージの壁に直面するのは、すべての JavaScript 開発者が通る道です。macOS でのパーミッションエラー、monorepo での依存関係の競合、CI でのキャッシュ破損など、原因がわかれば修正は通常簡単です。このガイドではよくある npm install エラーすべてを網羅し、原因を説明し、修正コマンドを提供します。

エラー辞書：クイックリファレンス

EACCES：パーミッションエラーの修正

macOS と Linux で最もよくあるエラーです。npm がグローバルパッケージを /usr/local/lib/node_modules のようなシステムディレクトリにインストールしようとすると発生します。

macOS / Linux での修正（推奨：nvm を使用）

最善の恒久的な修正は Node バージョンマネージャーを使用することです。npm がホームディレクトリにインストールされます：

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install Node
nvm install --lts
nvm use --lts

# Verify — npm now installs to ~/.nvm/
which npm
# /home/youruser/.nvm/versions/node/v20.x.x/bin/npm

代替手段：npm のデフォルトディレクトリを手動で変更：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc:
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

最終手段（ほとんどのユーザーには非推奨）：

# NOT recommended — changes system directory ownership
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/share

Windows での修正

Windows では管理者としてターミナルを実行するか、nvm-windows を使用：

# Install nvm-windows from:
# https://github.com/coreybutler/nvm-windows/releases

# Then in an elevated (Admin) PowerShell:
nvm install lts
nvm use lts

# Or fix npm prefix for current user:
npm config set prefix %APPDATA%\npm

ERESOLVE：依存関係の競合を修正

npm 7 以降、peer 依存関係の競合はデフォルトでインストールを失敗させます。競合するパッケージを示すツリー図が表示されます。

典型的なエラー出力：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @some-org/some-package@2.1.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-library@3.5.0
npm ERR! node_modules/some-library
npm ERR!   some-library@"^3.5.0" from the root project

--legacy-peer-deps と --force の違い

--legacy-peer-deps は npm に peer 依存関係の競合を完全に無視するよう指示します（npm 6 と同じ動作）。--force は競合に関係なくインストールを強制します。使い分け：

# Option 1: Ignore peer deps (safest workaround)
npm install --legacy-peer-deps

# Option 2: Force install (overrides everything)
npm install --force

推奨アプローチ — 競合する依存関係をピン留め：

// In package.json — add "overrides" to pin the conflicting dep
{
  "overrides": {
    "some-library": {
      "react": "^18.2.0"
    }
  }
}

// Then run:
// npm install

node_modules の破損：いつ・どのように削除して再インストールするか

node_modules は時々異常な状態になります。package.json にあるパッケージの "Cannot find module" エラーや、ブランチ切り替え後の奇妙なビルド失敗が症状です。

node_modules を削除すべきタイミング

• 異なる依存関係ツリーのブランチに切り替えた後。
• package-lock.json のマージコンフリクトを解決した後。
• 明らかにインストール済みのパッケージで "Module not found" が出る場合。
• Node.js をメジャーバージョンにアップグレードした後。

クリーンインストールの方法

クロスプラットフォームワンライナー（bash）：

rm -rf node_modules package-lock.json
npm install

Windows（PowerShell）：

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

npx を使った便利な方法：

npx rimraf node_modules
npm install

問題が解決しない場合は npm キャッシュもクリア：

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

package-lock.json の競合：マージ戦略

複数の開発者が依存関係を変更すると、package-lock.json のマージコンフリクトはほぼ確実に発生します。手動で解決しようとしないでください — このファイルは機械生成です。

推奨マージ戦略

競合のどちらか一方を受け入れる（どちらでも良い）：

# Accept "theirs" (the incoming branch's version)
git checkout --theirs package-lock.json
git add package-lock.json

# OR accept "ours" (your branch's version)
git checkout --ours package-lock.json
git add package-lock.json

ロックファイルを再生成：

npm install

結果をコミット：

git add package-lock.json
git commit -m "chore: regenerate package-lock.json after merge"

.gitattributes でコンフリクトを防止

.gitattributes に以下を追加してロックファイルのコンフリクトを自動解決：

# .gitattributes
package-lock.json merge=ours

Node.js バージョンの非互換性

多くのパッケージは特定の Node.js バージョンを必要とします。Node バージョンが古すぎる（または新しすぎる）と、コンパイルエラーやエンジン警告で npm install が失敗する可能性があります。

必要なバージョンの確認

package.json の engines フィールドを確認：

// package.json
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

// Check your current version:
// node -v
// npm -v

nvm または fnm でバージョンを切り替え

nvm（Node Version Manager）：

# List available versions
nvm ls-remote

# Install a specific version
nvm install 20

# Switch to a version
nvm use 20

# Set a default
nvm alias default 20

fnm（Fast Node Manager）— より高速な代替手段：

# Install fnm (Rust-based, faster than nvm)
curl -fsSL https://fnm.vercel.app/install | bash

# Install and use a version
fnm install 20
fnm use 20
fnm default 20

プロジェクトルートに .nvmrc ファイルを作成してチーム全体で同じバージョンを使用：

# Create .nvmrc file
echo "20" > .nvmrc

# Team members just run:
nvm use
# or
fnm use

CI/CD の問題：Docker ビルドと GitHub Actions

npm install は CI 環境では動作が異なります。キャッシュ、パーミッション、ネットワーク設定すべてに注意が必要です。

Docker ビルド

Dockerfile でよくある間違い：

# BAD Dockerfile — no layer caching, uses npm install
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

# GOOD Dockerfile — proper layer caching, uses npm ci
FROM node:20-alpine
WORKDIR /app

# Copy package files first (layer caching!)
COPY package.json package-lock.json ./

# Use npm ci for deterministic installs
RUN npm ci --ignore-scripts

# Then copy the rest of the source
COPY . .

# Run any build steps after copy
RUN npm run build

CMD ["node", "index.js"]

ポイント：レイヤーキャッシュのためにまず package ファイルをコピー、CI では npm install の代わりに npm ci を使用（高速で決定的）、postinstall スクリプトが不要なら --ignore-scripts を使用。

GitHub Actions キャッシュ

適切なキャッシュでインストール時間を 70% 以上短縮できます：

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'  # Caches ~/.npm automatically

      - run: npm ci       # Deterministic install
      - run: npm test
      - run: npm run build

決定フローチャート：npm install 失敗時のガイド

このフローチャートで npm install の失敗を診断してください：

よくある質問