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

概要

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用設定

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用設定

// 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用設定

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'
  ]
});

📝 必須の環境設定

日本語フォントとロケール設定

# 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

✅ 動作確認方法

# 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 オプションを追加

{
  allowDangerous: true  // 開発環境でのみ使用
}

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

問題3: GPU関連エラー

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

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

解決策:

args: [
  '--disable-gpu',
  '--disable-software-rasterizer'  // 必要に応じて追加
]

問題4: 日本語文字化け

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

原因:

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

詳細解決手順:

1. システムレベルでの日本語対応:

   sudo apt install fonts-noto-cjk fonts-noto-cjk-extra language-pack-ja
   sudo locale-gen ja_JP.UTF-8
   

2. ブラウザレベルでの言語設定:

   args: ['--lang=ja']
   

3. CSS強制設定（必要な場合）:

   // ブラウザ内で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証明書の問題

解決策:

args: [
  '--ignore-certificate-errors',
  '--ignore-ssl-errors',
  '--allow-running-insecure-content'
]

環境確認コマンド

WSLg環境が正常に動作しているかの確認：

# 期待される出力例
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ツールとの組み合わせにより、より強力な開発環境を構築できるでしょう。