Playwright MCP 在 WSL1 下的配置指南

折腾了一下午测试的几种方案,今天的活儿都没干 :face_holding_back_tears:

背景

虽然 WSL2 在 Windows 11 或新版 WSLg 中已支持 GUI 应用,可以直接运行图形化界面程序,但 WSL2 使用 9p 文件协议访问 Windows 文件系统,其性能远低于 WSL1 的原生文件访问。对于需要频繁进行文件 I/O 操作的开发场景,WSL1 的文件性能优势更为明显。因此,在某些性能要求较高的开发环境中选择 WSL1。

在 WSL1 环境下使用图形化界面软件存在诸多不便。Playwright 是一个基于 Chrome 浏览器的测试框架,下面介绍在 WSL1 环境下使用 Playwright 进行测试的几种解决方案。


方案零:使用 X11 转发(不推荐)

通过在 Windows 上运行 X Server(如 VcXsrv),将 WSL1 中的 GUI 应用转发到 Windows 显示。此方案性能较差,且配置复杂,极不推荐使用。

步骤 1:在 Windows 10 安装并启动 VcXsrv

  1. 安装 VcXsrv(Windows 上)

  2. 打开 XLaunch,建议配置如下:

  • Multiple windows

  • Start no client

  • Extra settings:

  • :white_check_mark: Disable access control(省事)

  • :white_check_mark: Clipboard(建议)

  1. 第一次启动如果弹防火墙:允许 Private networks

步骤 2:在 WSL1 中配置 DISPLAY 环境变量

在 WSL1 中执行:


export DISPLAY=:0

验证配置:


echo $DISPLAY

若想永久生效,写入 ~/.bashrc:


echo 'export DISPLAY=:0' >> ~/.bashrc

source ~/.bashrc

步骤 3:安装测试程序并验证 X11 是否连通


sudo apt update

sudo apt install -y x11-apps

xclock

如果能弹出窗口,说明 X11 转通正常。

步骤 4:配置 MCP(以 Codex 为例)

确认 X11 转发正常后,Playwright 可以正常使用 GUI 模式。

MCP 配置(以 Codex 为例):


[mcp_servers.playwright]

command = "npx"

args = ["-y", "@playwright/mcp@latest"]

注意: 此方案在 WSL1 + Windows 10 环境下,Windows XServer 在 Windows 下渲染,性能极差,不建议在生产环境中使用。


方案一:使用 Playwright 的 Headless 模式

在 Headless 模式下,Playwright 不会显示浏览器窗口,适用于服务器或无头环境。

MCP 配置(以 Codex 为例):


[mcp_servers.playwright]

command = "npx"

args = ["-y", "@playwright/mcp@latest", "--headless=true"]


方案二:使用 Playwright 的 Extension 模式(未测试通过)

在 Chrome 或 Edge 浏览器中安装 Playwright MCP Bridge 扩展,打开扩展复制 PLAYWRIGHT_MCP_EXTENSION_TOKEN,然后在 MCP 配置中添加环境变量。此方案会调用宿主机打开的浏览器。

MCP 配置(以 Codex 为例):


[mcp_servers.playwright]

type = "stdio"

command = "npx"

args = ["-y", "@playwright/mcp@latest", "--extension"]

[mcp_servers.playwright.env]

PLAYWRIGHT_MCP_EXTENSION_TOKEN="Wu82zcHem7JVAzlsy0fyDeFKbQgB82pYe9N7nIZ5Uh0"


方案三:使用 Playwright 的 Streamable HTTP 模式(推荐)

在宿主机安装并配置好 Playwright,然后执行以下命令:

在宿主机执行:


npx -y @playwright/mcp@latest --host 0.0.0.0 --port 8931

在 MCP 客户端配置(以 Codex 为例):


[mcp_servers.playwright]

url = "http://localhost:8931/mcp"


方案四:使用 Playwright 的 CDP 协议模式(推荐)

出处:在wsl中使用codex,配置playwright连接远程浏览器调试

前提条件: 确保 WSL 和外部系统网络保持畅通。

步骤 0:在 Windows 启动 Chrome 浏览器并监听端口

使用 --user-data-dir 设置用户目录:


"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\chrome_dev" --remote-debugging-address=0.0.0.0

步骤 1:确认端口监听状态

在 Windows PowerShell 中执行:


netstat -ano | findstr 9222

输出示例:


TCP 127.0.0.1:9222 0.0.0.0:0 LISTENING 12345

步骤 2:在 WSL 中查找 Windows 主机 IP


cat /etc/resolv.conf | grep nameserver

输出示例:


nameserver 172.21.48.1

步骤 3:测试连接


curl http://172.21.48.1:9222/json/version

请求返回 JSON 数据,获取 webSocketDebuggerUrl:


{

"Browser": "Chrome/135.0.7049.85",

"Protocol-Version": "1.3",

"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",

"V8-Version": "13.5.212.10",

"WebKit-Version": "537.36 (@1e112499da812a1dde62101ed601dcb93024aaff)",

"webSocketDebuggerUrl": "ws://172.21.48.1:9222/devtools/browser/35a1c7e5-c863-49c1-bf13-ec6d88717a20"

}

步骤 4:在 MCP 客户端配置,使用 CDP 协议(以 Codex 为例)

注意: 务必使用正确的 webSocketDebuggerUrl


[mcp_servers.playwright]

command = "npx"

args = ["@playwright/mcp@latest", "--cdp-endpoint", "ws://172.21.48.1:9222/devtools/browser/35a1c7e5-c863-49c1-bf13-ec6d88717a20"]

5 个赞

感谢大佬