WSL環境のPuppeteer/Playwright MCPでブラウザの中身がうまく表示されない時の対策

## 概要

![スクリーンショット 2025-06-15 020013.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1242618/c5d59e6a-a58f-468f-93db-01e5aab9f1b4.png)

Windows 11のWSLg環境でPuppeteerやPlaywright、そしてClaude Code MCPツールを使ったブラウザ自動化を行う際、多くの開発者が以下のような問題に直面します：

- ブラウザウィンドウは開くが中身が真っ白
- 日本語が文字化けする（□□□で表示される）
- "Dangerous browser arguments detected" エラー
- GPU関連エラーで起動に失敗
- SSL証明書エラーでページが表示されない

**対象読者**: Windows 11 + WSL2 + WSLg環境でブラウザ自動化を行う開発者
**前提環境**: Windows 11、WSL2有効、WSLg有効（標準で有効）、Ubuntu 20.04以降

これらの問題は、WSLg特有の環境設定に起因しており、適切な設定を行うことで確実に解決できます。

## 結論（すぐ使える解決策）

### 🚀 即座に使える推奨設定

#### Puppeteer用設定
```javascript
const puppeteer = require('puppeteer');

const browser = await puppeteer.launch({
  headless: false,
  args: [
    '--disable-dev-shm-usage',
    '--disable-gpu',
    '--remote-debugging-port=9222',
    '--ignore-certificate-errors',
    '--ignore-ssl-errors',
    '--allow-running-insecure-content',
    '--lang=ja'
  ],
  allowDangerous: true
});
```

#### Claude Code MCP用設定
```javascript
// mcp__puppeteer__puppeteer_navigate ツールの場合
{
  "url": "https://localhost:3000/",
  "launchOptions": {
    "headless": false,
    "args": [
      "--disable-dev-shm-usage",
      "--disable-gpu",
      "--remote-debugging-port=9222",
      "--ignore-certificate-errors",
      "--ignore-ssl-errors",
      "--allow-running-insecure-content",
      "--lang=ja"
    ]
  },
  "allowDangerous": true
}
```

#### Playwright用設定
```javascript
const { chromium } = require('playwright');

const browser = await chromium.launch({
  headless: false,
  args: [
    '--disable-dev-shm-usage',
    '--disable-gpu',
    '--ignore-certificate-errors',
    '--ignore-ssl-errors',
    '--allow-running-insecure-content',
    '--lang=ja'
  ]
});
```

### 📝 必須の環境設定

#### 日本語フォントとロケール設定
```bash
# 1. 日本語フォントのインストール
sudo apt update
sudo apt install -y fonts-noto-cjk fonts-noto-cjk-extra language-pack-ja

# 2. ロケールの生成
sudo locale-gen ja_JP.UTF-8

# 3. 環境変数の設定（セッション毎に実行）
export LANG=ja_JP.UTF-8
export LC_ALL=ja_JP.UTF-8
```

### ✅ 動作確認方法
```bash
# WSLg環境の確認
echo "DISPLAY: $DISPLAY"
echo "WAYLAND_DISPLAY: $WAYLAND_DISPLAY"

# ブラウザ直接起動テスト
google-chrome https://www.google.com
```

## 詳細解説

### 問題1: ブラウザウィンドウが真っ白

**症状**: ブラウザウィンドウは表示されるが、内容が真っ白でレンダリングされない

**原因**: WSLg環境でのGPU加速とブラウザレンダリングエンジンの競合

**解決策**: 
- `--disable-gpu`: GPU加速を無効化
- `--disable-dev-shm-usage`: 共有メモリ使用を無効化

これらのオプションにより、WSLg環境でも安定したレンダリングが可能になります。

### 問題2: "Dangerous browser arguments detected" エラー

**症状**: Puppeteerやブラウザ自動化ツールでセキュリティエラーが発生

**原因**: ブラウザの安全性オプションが制限されている

**解決策**: `allowDangerous: true` オプションを追加
```javascript
{
  allowDangerous: true  // 開発環境でのみ使用
}
```

**注意**: 本番環境では使用しないこと

### 問題3: GPU関連エラー

**症状**: ブラウザ起動時にGPU関連のエラーメッセージが表示される

**原因**: WSLg環境でのハードウェアアクセラレーション設定の問題

**解決策**: 
```javascript
args: [
  '--disable-gpu',
  '--disable-software-rasterizer'  // 必要に応じて追加
]
```

### 問題4: 日本語文字化け

**症状**: 日本語テキストが □□□ や意味不明な文字で表示される

**原因**: 
- WSL環境に日本語フォントが未インストール
- 適切なロケール設定がされていない

**詳細解決手順**:
1. **システムレベルでの日本語対応**:
   ```bash
   sudo apt install fonts-noto-cjk fonts-noto-cjk-extra language-pack-ja
   sudo locale-gen ja_JP.UTF-8
   ```

2. **ブラウザレベルでの言語設定**:
   ```javascript
   args: ['--lang=ja']
   ```

3. **CSS強制設定**（必要な場合）:
   ```javascript
   // ブラウザ内でJavaScript実行
   document.head.insertAdjacentHTML('beforeend', 
     '<style>* { font-family: "Noto Sans CJK JP", "Yu Gothic", "Meiryo", sans-serif !important; }</style>'
   );
   ```

### 問題5: SSL証明書エラー

**症状**: HTTPSサイトで「net::ERR_CERT_AUTHORITY_INVALID」エラー

**原因**: 開発環境での自己署名証明書やlocalhost証明書の問題

**解決策**:
```javascript
args: [
  '--ignore-certificate-errors',
  '--ignore-ssl-errors',
  '--allow-running-insecure-content'
]
```

### 環境確認コマンド

WSLg環境が正常に動作しているかの確認：
```bash
# 期待される出力例
echo "DISPLAY: $DISPLAY"        # DISPLAY: :0
echo "WAYLAND_DISPLAY: $WAYLAND_DISPLAY"  # WAYLAND_DISPLAY: wayland-0
```

### トラブルシューティングのフロー

1. **基本確認**: WSLg環境変数の確認
2. **フォント設定**: 日本語フォントとロケールの設定
3. **ブラウザオプション**: 推奨設定の適用
4. **動作確認**: 直接ブラウザ起動でのテスト
5. **自動化テスト**: PuppeteerやPlaywrightでの動作確認

### まとめ

WSL環境でのブラウザ自動化は、適切な設定を行うことで確実に動作します。重要なポイントは：

- **GPU加速の無効化**: `--disable-gpu`
- **セキュリティ設定**: `allowDangerous: true`（開発環境限定）
- **日本語対応**: フォントインストールと`--lang=ja`
- **SSL対応**: 証明書エラー無視設定

これらの設定により、WSLg環境でも本格的なブラウザ自動化が可能になり、開発効率を大幅に向上させることができます。Claude Code MCPツールとの組み合わせにより、より強力な開発環境を構築できるでしょう。