07 トラブルシューティング

このドキュメントでは、DevBlueprint プロジェクトのセットアップ・開発時によく発生する問題とその解決方法をまとめています。

1. 一般的な問題の診断

1.1 問題の特定手順

問題が発生した際は、以下の順序で原因を特定してください：

1. エラーメッセージの確認 - 具体的なエラー内容を読む
2. 環境の確認 - OS、Node.js、npm のバージョンをチェック
3. 設定ファイルの確認 - JSON構文エラーやパス設定をチェック
4. 依存関係の確認 - package.json と実際のインストール状況を比較
5. ログの確認 - VS Code の出力パネルやターミナルのログを確認

1.2 情報収集コマンド

# システム情報の取得
node --version
npm --version
git --version
code --version

# プロジェクト情報の取得
npm list --depth=0
npm outdated
npm audit

# 環境変数の確認
echo $NODE_ENV
echo $PATH

2. 環境構築に関する問題

2.1 Node.js のインストール問題

問題: Node.js がインストールできない

症状:

• インストーラーが失敗する
• コマンドが見つからない（command not found）

解決方法:

# 1. 管理者権限で実行（Windows）
# PowerShell を管理者として実行

# 2. 既存のNode.js を完全にアンインストール
# Windows: コントロールパネルから削除
# macOS: /usr/local から関連ファイルを削除
sudo rm -rf /usr/local/lib/node*
sudo rm -rf /usr/local/include/node*

# 3. パッケージマネージャーを使用（推奨）
# Windows: Chocolatey
choco install nodejs

# macOS: Homebrew
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

問題: npm の権限エラー（Linux/macOS）

症状:

EACCES: permission denied, access '/usr/local/lib/node_modules'

解決方法:

# npm のグローバルディレクトリを変更
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# パスを設定（.bashrc または .zshrc に追加）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

2.2 Git の設定問題

問題: Git の認証エラー

症状:

remote: Support for password authentication was removed

解決方法:

# 1. Personal Access Token を使用
git config --global credential.helper store

# 2. SSH キーの設定
ssh-keygen -t ed25519 -C "your_email@example.com"
cat ~/.ssh/id_ed25519.pub
# GitHub の Settings → SSH and GPG keys に追加

# 3. リモートURLの変更
git remote set-url origin git@github.com:username/repository.git

問題: Git の改行コード問題

症状:

• Windows で改行コードが混在する
• Unix/Linux で CRLF エラーが発生

解決方法:

# Windows の場合
git config --global core.autocrlf true

# Linux/macOS の場合
git config --global core.autocrlf input

# 既存ファイルの修正
git add --renormalize .
git commit -m "Normalize line endings"

3. VS Code の問題

3.1 拡張機能の問題

問題: 拡張機能が動作しない

症状:

• ESLint エラーが表示されない
• Prettier によるフォーマットが効かない

解決方法:

1. 拡張機能の再インストール

   # 拡張機能をリストして確認
   code --list-extensions
   
   # 特定の拡張機能を再インストール
   code --uninstall-extension esbenp.prettier-vscode
   code --install-extension esbenp.prettier-vscode
   

2. VS Code の設定確認

   // .vscode/settings.json の確認
   {
       "editor.defaultFormatter": "esbenp.prettier-vscode",
       "editor.formatOnSave": true,
       "eslint.validate": ["javascript", "typescript"]
   }
   

3. 出力パネルでエラー確認

   • Ctrl+Shift+U で出力パネルを開く
   • 右上のドロップダウンから「ESLint」や「Prettier」を選択

問題: IntelliSense が動作しない

症状:

• コード補完が表示されない
• TypeScript の型情報が表示されない

解決方法:

# 1. TypeScript サーバーの再起動
# VS Code のコマンドパレット（Ctrl+Shift+P）で実行
> TypeScript: Restart TS Server

# 2. キャッシュのクリア
rm -rf node_modules/.cache
rm -rf .vscode/.tscache

# 3. 依存関係の再インストール
rm -rf node_modules package-lock.json
npm install

3.2 ワークスペースの問題

問題: タスクが実行できない

症状:

• Tasks: Run Task で定義したタスクが表示されない
• タスク実行時にエラーが発生

解決方法:

1. tasks.json の構文確認

   {
       "version": "2.0.0",
       "tasks": [
           {
               "label": "lint",
               "type": "shell",
               "command": "npm",
               "args": ["run", "lint"],
               "group": "build"
           }
       ]
   }
   

2. スクリプトの存在確認

   # package.json のスクリプトを確認
   npm run
   

4. 依存関係の問題

4.1 パッケージインストールの問題

問題: npm install でエラーが発生

症状:

npm ERR! peer dep missing
npm ERR! network timeout

解決方法:

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

# 2. package-lock.json の削除と再生成
rm package-lock.json
rm -rf node_modules
npm install

# 3. registry の変更
npm config set registry https://registry.npmjs.org/

# 4. プロキシ設定の確認（企業環境の場合）
npm config list
npm config delete proxy
npm config delete https-proxy

問題: パッケージのバージョン競合

症状:

npm WARN peer dep missing
npm ERR! conflicting peer dependency

解決方法:

# 1. 依存関係の確認
npm ls
npm outdated

# 2. ピア依存関係の手動インストール
npm install <missing-peer-dependency>

# 3. 強制的な依存関係解決（注意して使用）
npm install --force
npm install --legacy-peer-deps

4.2 バージョン管理の問題

問題: セマンティックバージョンの競合

解決方法:

# 1. 特定バージョンの固定
npm install package@1.2.3 --save-exact

# 2. バージョン範囲の調整
# package.json で "^1.0.0" → "~1.0.0"

# 3. npm-check-updates を使用
npx npm-check-updates -u
npm install

5. リンター・フォーマッター の問題

5.1 ESLint の問題

問題: ESLint エラーが大量に表示される

解決方法:

# 1. 自動修正可能なエラーを修正
npm run lint:fix

# 2. 特定のルールを無効化
# .eslintrc.json で調整
{
  "rules": {
    "no-console": "warn",  // "error" から "warn" に変更
    "no-unused-vars": "off"  // 完全に無効化
  }
}

# 3. ファイルごとの例外設定
/* eslint-disable no-console */
console.log('debug info');
/* eslint-enable no-console */

問題: TypeScript でのESLint設定問題

解決方法:

// .eslintrc.json
{
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "project": "./tsconfig.json"
    },
    "plugins": ["@typescript-eslint"],
    "rules": {
        "@typescript-eslint/no-unused-vars": "error",
        "no-unused-vars": "off"
    }
}

5.2 Prettier の問題

問題: Prettier と ESLint の設定競合

解決方法:

# eslint-config-prettier をインストール
npm install --save-dev eslint-config-prettier

# .eslintrc.json の extends に追加
{
  "extends": [
    "eslint:recommended",
    "prettier"  // 最後に追加
  ]
}

問題: 特定ファイルのフォーマット除外

解決方法:

# .prettierignore
package-lock.json
dist/
build/
*.min.js
CHANGELOG.md

6. テストの問題

6.1 Jest の設定問題

問題: モジュールが見つからない

症状:

Cannot find module '@/components/Button'

解決方法:

// jest.config.js
module.exports = {
    moduleNameMapping: {
        '^@/(.*)$': '<rootDir>/src/$1',
    },
    testEnvironment: 'jsdom', // フロントエンド用
};

問題: TypeScript ファイルのテスト実行エラー

解決方法:

# ts-jest をインストール
npm install --save-dev ts-jest @types/jest

# jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node'
};

7. CI/CD の問題

7.1 GitHub Actions の問題

問題: ワークフローが失敗する

解決方法:

1. ログの詳細確認

   • GitHub Actions タブで失敗したステップをクリック
   • デバッグログを有効化: リポジトリに ACTIONS_STEP_DEBUG=true シークレットを追加

2. ローカルでの再現

   # 同じコマンドをローカル環境で実行
   npm ci
   npm run lint
   npm run test
   

3. キャッシュの問題

   # actions/cache のキーを変更
   - uses: actions/cache@v3
     with:
         path: ~/.npm
         key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}-v2
   

7.2 Husky の問題

問題: Git フックが実行されない

解決方法:

# 1. Husky の再初期化
rm -rf .husky
npx husky install
npx husky add .husky/pre-commit "npm run lint:fix"

# 2. 権限の確認（Linux/macOS）
chmod +x .husky/pre-commit

# 3. Git フックの確認
ls -la .git/hooks/

8. パフォーマンスの問題

8.1 VS Code の動作が重い

解決方法:

// settings.json
{
    "search.exclude": {
        "**/node_modules": true,
        "**/dist": true,
        "**/.git": true
    },
    "files.watcherExclude": {
        "**/node_modules/**": true,
        "**/.git/objects/**": true
    }
}

8.2 大きなプロジェクトでのリント・フォーマット性能

解決方法:

# 1. ファイル数の制限
echo "node_modules/" >> .eslintignore
echo "dist/" >> .prettierignore

# 2. 並列実行の活用
npm install --save-dev concurrently
# package.json
{
  "scripts": {
    "lint:parallel": "concurrently \"npm run lint:js\" \"npm run lint:css\""
  }
}

9. セキュリティの問題

9.1 npm audit の脆弱性警告

解決方法:

# 1. 自動修正の実行
npm audit fix

# 2. 強制的な修正（注意して使用）
npm audit fix --force

# 3. 特定の脆弱性の無視
npm audit --audit-level moderate

9.2 依存関係のセキュリティ

解決方法:

# 1. 定期的な依存関係の更新
npx npm-check-updates -u
npm install

# 2. セキュリティ専用ツールの使用
npm install -g snyk
snyk test
snyk fix

10. ヘルプとサポート

10.1 追加のリソース

• 公式ドキュメント

  • Node.js Documentation
  • VS Code Documentation
  • ESLint Rules
  • Prettier Options

• コミュニティサポート

  • Stack Overflow
  • GitHub Discussions
  • [Discord/Slack コミュニティ]

10.2 問題報告の方法

問題を報告する際は、以下の情報を含めてください：

## 環境情報

- OS: Windows 10 / macOS 12.0 / Ubuntu 20.04
- Node.js: v18.17.0
- npm: v9.6.7
- VS Code: v1.80.0

## 問題の詳細

- 発生したエラーメッセージ
- 実行したコマンド
- 期待される動作と実際の動作

## 再現手順

1. ...
2. ...
3. ...

## 追加情報

- 関連するログファイル
- スクリーンショット（必要に応じて）

11. よくあるFAQ

Q: 「command not found」エラーが発生します

A: PATH環境変数の設定を確認してください。ターミナルを再起動するか、設定を再読み込みしてください。

Q: 依存関係の警告が多数表示されます

A: 古いパッケージや非推奨の設定が原因です。npm outdatedで確認し、段階的に更新してください。

Q: テストが CI でのみ失敗します

A: 環境固有の設定やタイムゾーン、ファイルパスの問題が考えられます。CI環境でのデバッグログを確認してください。

---

このトラブルシューティングガイドで解決しない問題がある場合は、チーム内で相談するか、GitHub Issues で報告してください。