Windows上Claude Code配Playwright MCP踩坑记录

最近项目里要给 Claude Code 配上浏览器操作能力，我选了社区里最常见的方案：Playwright MCP。折腾下来说实话，Windows 上比 macOS 和 Linux 要烦不少，光是“npx 找不到”“浏览器内核起不来”“MCP server 连不上”这三个问题就让我来回折腾了一个晚上。如果你也在 Windows 上配置 Claude Code + Playwright MCP，这篇踩坑记应该能帮你少走不少弯路。

我会先讲清楚这套东西到底是怎么串起来的，然后给出一份可以直接照着做的配置步骤，最后把我踩过的三个坑拆开讲明白——每个坑都附上当时的具体报错和最终解决办法，配置过程中卡住的朋友可以直接跳到第三节对着排查。

1. 整体设计思路：Claude Code、Playwright、MCP 是怎么串起来的

1.1 MCP 到底解决了什么问题

MCP 的全称是 Model Context Protocol，它解决的核心问题是：让大模型和外部工具之间有一个标准化的通信接口。你可以把它理解成 USB 接口——设备端只要遵循同一套协议，插上就能用，不用每个硬件厂商各自定义一套专属接口。

在 Claude Code 这个场景里，Claude Code 本身是 MCP 的客户端（Host），Playwright MCP 是一个 MCP Server。配置完成之后，Claude Code 就能通过 MCP 调用 Playwright 提供的浏览器工具，比如打开页面、点击按钮、填写表单、提取文本、截图等。模型不再只是“看着代码猜页面行为”，而是可以真实地看到页面状态，再根据页面反馈做下一步操作。

这对做端到端测试、页面自动化检查、数据抓取这类任务特别实用。以前写爬虫或者做 UI 自动化测试，要手动写脚本处理各种选择器、等待条件、页面跳转，现在可以让 Claude Code 直接操作浏览器，遇到异常还能现场调试。

1.2 为什么选择 Playwright MCP，而不是让 Claude 直接写脚本

可能有人会问：Claude Code 本身就能写 Playwright 脚本，为什么还要额外接一个 MCP server？

我一开始也是这么想的，直到被现实教育了。直接让 Claude 生成一段 Playwright 脚本再执行，脚本跑完你只能拿到一个最终结果，中间哪一步失败了、页面实际长什么样、元素有没有加载出来，模型都是“瞎”的。它只能根据报错文本去猜，而 Playwright 的报错往往很抽象，比如 timeout 超时、element not found，但真正的原因可能是页面跳转慢、iframe 没切换、或者某个请求被反爬拦截了。

接了 Playwright MCP 之后，模型可以一步步操作浏览器：打开页面、等待加载、截图看当前状态、读取控制台日志、修改输入框内容，再继续操作。整个过程就像一个人坐在电脑前真实操作浏览器，而不是盲写脚本。尤其是处理动态渲染页面、iframe、需要登录的场景，这种“边看边做”的模式成功率会高很多。

1.3 Windows 下的完整调用链路

在 Windows 上，这条链路的每一个环节都可能出问题：

Claude Code（MCP 客户端） ↓ 通过 MCP 协议调用 npx 启动 @playwright/mcp（MCP Server） ↓ 通过 Playwright 驱动 浏览器内核（Chromium / Chrome / Edge） ↓ 执行 真实页面操作

配置过程中遇到的大部分问题，都可以定位到这条链路的某一环上：要么是 Claude Code 没有正确拉起 npx，要么是 npx 没有正确安装依赖，要么是浏览器内核下载失败，要么是 MCP Server 启动后连接超时。

我把这三个坑总结一下：

• 坑一：Claude Code 找不到 npx，报spawn npx ENOENT。
• 坑二：Playwright 浏览器内核下载失败，或者启动时提示找不到浏览器执行文件。
• 坑三：MCP Server 启动后反复连接超时，最后 Claude Code 直接显示工具不可用。

下面会逐一拆解，先讲环境准备和标准配置流程，再讲这三个坑的详细解决方案。

2. 配置前必须做好的环境准备

2.1 Node.js 和 npm：Windows 最容易忽略的 PATH 问题

Playwright MCP 是通过 npm 生态分发的，所以 Node.js 是第一个必须装好的依赖。我推荐直接去 Node.js 官网下载 LTS 版本安装包，不要用某些工具链自带的旧版本 Node，版本太老会导致@playwright/mcp跑不起来。

安装的时候留意两个点：

1. 安装路径不要带空格。默认路径是C:\Program Files\nodejs\，虽然一般情况下没问题，但后续在 JSON 配置文件里写路径时，带空格的路径很容易因为转义问题踩坑。我自己的做法是装到D:\nodejs\，省心很多。
2. 安装完成后确认 PATH 环境变量。装完之后可以打开一个新的 PowerShell 窗口，分别执行node -v和npm -v。如果提示“node 不是内部或外部命令”，说明 PATH 没有生效，需要手动把 Node.js 安装目录加进系统环境变量的 Path 里。

很多 Windows 用户卡在“Claude Code 找不到 npx”，根源就是 PATH 配置不完整。这里有个细节：修改完系统环境变量之后，已经打开的所有终端窗口都不会自动刷新环境变量，你必须完全关闭 PowerShell / CMD / VS Code，重新打开，配置才会生效。

2.2 安装 Playwright MCP 与浏览器内核

环境变量没问题之后，先确认 npx 能正常工作：

npx --version

然后可以用 npx 直接启动一次 Playwright MCP，验证能不能跑起来：

npx @playwright/mcp@latest --help

如果这一步能正常输出参数说明，说明 MCP Server 本身可以启动。接下来需要安装浏览器内核：

npx playwright install chromium

这一步是 Windows 上最容易卡住的环节，原因后面专门讲。如果你的机器上已经装了 Chrome 或者 Edge，也可以不下载 Chromium，直接让 Playwright 复用系统浏览器，具体配置方法见 3.3 节。我个人建议先安装 Chromium，因为复用 Edge 的时候有时会遇到版本匹配问题。

2.3 PowerShell 执行策略：很多“无响应”的隐藏原因

Windows 默认的 PowerShell 执行策略是 Restricted，这会导致某些 .ps1 脚本无法执行。Claude Code 安装时如果有脚本注册的步骤，可能因此失败。

建议将当前用户的执行策略改为 RemoteSigned：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

改成 RemoteSigned 之后，本地创建的脚本可以运行，从网上下载的脚本需要带有可信签名。这是 Windows 下兼顾安全性和可用性的一个折中方案。

做完这些准备工作，就进入正式配置环节了。

3. 实操过程：从零到一配置 Playwright MCP

3.1 方式一：通过命令行添加 MCP Server

Claude Code 提供了claude mcp add命令来管理 MCP Server。打开一个终端，执行：

claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium

这里拆解一下：

• playwright是给你的 MCP Server 起的名字，可以随意改，比如叫browser或mcp-playwright。
• --后面的内容是实际启动命令。
• --browser chromium是指定使用 Chromium 内核。如果你想让 Playwright 复用系统自带的 Edge，可以改成--browser msedge。

添加完成之后，用下面的命令确认状态：

claude mcp list

如果输出里有playwright，并且状态显示connected，那就是配置成功了。如果显示error或者failed，就去看下一节的踩坑记录。

注意：claude mcp add默认添加的是“用户级”配置，也就是说你所有项目里都能用这个 MCP Server。如果你只想在某个项目里使用，要加--scope project参数，或者直接手动写项目配置文件。

3.2 方式二：手动编写 .mcp.json 配置

手动写配置文件的好处是可控性更强，而且能直观看到参数是怎么传给 MCP Server 的。在项目根目录下创建.mcp.json文件：

{ "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest", "--browser", "chromium" ] } } }

如果你是手动创建这个文件，有两点要特别注意：

1. 文件编码必须是 UTF-8。用 VS Code 保存时确认右下角编码是 UTF-8，不要用 GBK。Windows 记事本保存的 UTF-8 带 BOM，有时也会导致 JSON 解析失败。
2. Windows 下如果 npx 路径识别有问题，command可以改成 npx 的绝对路径，通常长这样：

{ "mcpServers": { "playwright": { "command": "C:\\Program Files\\nodejs\\npx.cmd", "args": [ "@playwright/mcp@latest", "--browser", "chromium" ] } } }

注意这里 JSON 里的反斜杠要写成\\，否则转义会出错。这是我在坑三里踩到的具体问题，后面会展开说。

还有一种更保险的写法：如果你知道 npx 在系统里的具体位置，可以直接用where npx查一下，拿到完整路径之后填进去。绝大多数 Windows 上的报错，本质上都是因为 Claude Code 拉起的子进程没有继承终端里的完整 PATH，导致npx这个命令找不到，用绝对路径能绕开这个问题。

3.3 复用系统 Edge / Chrome，省去下载内核

如果你不想下载 Chromium，可以复用系统自带的 Edge。在配置参数里指定浏览器名称就行：

{ "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest", "--browser", "msedge", "--isolated", "false" ] } } }

这里加了一个--isolated false，意思是让 Playwright 直接连接系统浏览器，而不是启动一个干净的测试实例。这样你日常登录过的网站，比如各种后台系统，都是处于已登录状态的，自动化操作的时候不用再走一遍登录流程。

不过复用系统浏览器有个小问题：如果浏览器已经开了很多标签页，自动化操作可能会受到影响。我试下来 Edge 的表现比 Chrome 稳定一点，这也是很多人推荐直接用 Edge 的原因。

3.4 验证连接：让 Claude Code 真的去打开一个网页

配置完成后，进入 Claude Code 交互界面：

claude

然后直接输入一句自然语言指令，比如：

用浏览器打开 https://example.com，然后把页面的标题告诉我

如果一切正常，你会看到 Claude Code 调用一个类似mcp__playwright__browser_navigate的工具，接着是mcp__playwright__browser_snapshot，最后给出页面标题。看到工具被正常调用，说明整条链路已经通了。

如果你不确定工具到底有没有被调用，可以启动 Claude Code 时加--debug参数，或者直接在会话里输入/mcp查看当前 MCP Server 的连接状态。

4. 三个坑的完整复盘：报错、原因、解决办法

4.1 坑一：spawn npx ENOENT，Claude Code 找不到 npx

报错场景：我按照网上的教程执行了claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium，命令行工具的返回结果是添加成功，但claude mcp list里状态却是 error。点开详细日志，核心报错是：

spawn npx ENOENT

ENOENT 翻译过来就是“No such file or directory”，Claude Code 在尝试启动 npx 进程的时候，压根儿没找到 npx 这个文件。

问题原因：环境变量 PATH 在图形界面和命令行工具之间没有同步生效。我当时是在 VS Code 的终端里执行claude mcp add的，VS Code 是修改 PATH 之前启动的，它继承的是旧的环境变量，所以里头的子进程自然找不到 npx。

解决办法：分两步走。第一步，完全退出 VS Code 和终端窗口，重新打开，让进程重新加载最新的系统环境变量。第二步，如果重新打开后还是报 ENOENT，那就别用npx这个短命令，直接在配置里写 npx 的绝对路径。Windows 上通常是：

C:\Program Files\nodejs\npx.cmd

注意，Windows 下要写npx.cmd，不能只写npx。因为 Claude Code 底层是通过 Node.js 的 child_process 启动子进程，在 Windows 上它不会自动去找 .cmd 文件，直接写npx会踩到找不到可执行文件的坑。

验证方法：

where npx

把输出路径填到 MCP 配置的command字段里。填完之后再执行claude mcp list，状态从 error 变成 connected，这个坑就算填上了。

4.2 坑二：Playwright 浏览器内核下载失败或启动直接崩

报错场景：配置好 MCP Server 后，我让它打开网页，结果 Claude Code 返回了一长串错误，核心信息是：

Executable doesn't exist at C:\Users\xxx\AppData\Local\ms-playwright\chromium-xxxx\chrome-win\chrome.exe

或者：

Please run the Playwright install command

问题原因：MCP Server 能启动，不代表浏览器内核已经装好了。@playwright/mcp这个包本身只提供了控制层，真正的浏览器内核需要单独执行npx playwright install来下载。这里有两个 Windows 下常见的坑：一是下载地址被墙导致下载失败；二是下载完了解压路径不一致，导致 Playwright 找不到浏览器文件。

解决办法：先手动执行：

npx playwright install chromium

如果下载过程卡住或者报超时错误，可以配置镜像源：

$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright" npx playwright install chromium

国内网络环境下，这个镜像源能解决绝大多数下载失败的问题。下载完成后，Playwright 会提示浏览器被安装到了哪个目录，正常来说是在：

%USERPROFILE%\AppData\Local\ms-playwright\

如果执行完install命令之后还是提示找不到浏览器，可以手动检查一下这个目录里有没有对应的 chromium 文件夹。没有的话，删除掉%USERPROFILE%\AppData\Local\ms-playwright整个目录，重新执行安装命令。

补充一个经验：如果你想用系统自带的 Edge，可以不执行install，直接在 MCP 配置里加--browser msedge。Edge 的路径 Playwright 会自动探测，一般不会出问题。这也是我建议“不想折腾下载就直接用 Edge”的原因。

4.3 坑三：MCP Server 启动超时，连接反复失败

报错场景：配置好了 MCP Server，浏览器内核也装好了，但claude mcp list显示 playwright 一直处于 connecting 状态，过了一会儿变成 failed。终端里时不时冒出：

MCP server playwright timed out after 30000ms

问题原因：这个坑最隐蔽。第一个原因是，MCP Server 启动时，Claude Code 会等待 server 返回初始化响应，如果加了很多参数，比如--viewport-size、--headed、--proxy-server之类的，启动过程变长，超过了 30 秒的超时阈值，就会直接判定失败。

第二个原因是我在 Windows 上被坑到的：配置里的参数被拆分错了。比如我在 JSON 配置里写了：

"args": [ "@playwright/mcp@latest", "--browser", "chromium --headed" ]

注意，我把chromium --headed写成了一个字符串参数，MCP Server 会把--headed当成浏览器名称的一部分解析，导致启动异常。正确的写法是每个参数都是独立的一项：

"args": [ "@playwright/mcp@latest", "--browser", "chromium", "--headed" ]

这个问题在用命令行添加 MCP 时不会出现，因为 shell 会自动做参数拆分；但手动改 JSON 文件时特别容易犯，尤其是复制网上配置的时候，很多人不加检查就粘贴进去了。

第三个原因：端口被占用。Playwright MCP 默认会占用一个端口用于 Chrome DevTools 通信，如果之前有残留的调试进程还在运行，新启动的 server 就会绑定端口失败。

解决办法：

第一，去掉非必要的参数，先让 MCP Server 以最小参数跑起来，确认能连通之后再逐步加其他参数。

第二，如果确实需要启动时不带界面（headless），直接显式写：

"args": [ "@playwright/mcp@latest", "--browser", "chromium", "--headless" ]

第三，启动之前检查一下有没有残留的 Node.js 进程：

Get-Process node | Select-Object Id, ProcessName, Path

如果发现有之前测试留下的 node 进程，先 kill 掉再重新连接。

第四，如果反复超时，可以在配置里显式加上--port 0，让 MCP Server 每次随机选一个空闲端口，避免端口冲突。不过这种方式不太适合需要固定端口的调试场景，所以只作为临时排查手段。

4.4 问题速查表

5. 一些 Windows 下的补充建议

5.1 不要用 Git Bash 来启动 Claude Code

在 Windows 上，如果你习惯用 Git Bash，建议配置 MCP 时还是切回 PowerShell 或者 CMD。Git Bash 的路径转换机制会把/开头的参数自动转换成 Windows 路径，比如--browser chromium这种参数有时会被莫名改写成C:/Program Files/Git/browser chromium，导致 MCP Server 参数解析失败。

我一开始就是在 Git Bash 里配置的，折腾了半小时，最后换成 PowerShell 一次成功。这不是玄学，就是工具链的路径处理逻辑不同。

5.2 配置文件的搜索顺序

Claude Code 加载 MCP 配置时有优先级顺序：项目级.mcp.json会覆盖用户级配置。如果你在项目里手动创建了.mcp.json，但发现工具没生效，可以看看是不是项目配置路径写错了，或者文件被.gitignore忽略了。

我遇到过一种情况：项目根目录下有个旧的.mcp.json，格式已经过时了，Claude Code 优先读取了它，导致我新添加的用户级配置完全没被加载。排查了很久才发现是项目配置把用户配置“遮蔽”了。处理方法是把项目级配置修正，或者直接删掉不需要的项目级文件。

5.3 调试时善用 npx 直接启动

遇到问题别急着改来改去，先用命令行手工启动一次 MCP Server，看它能不能正常跑起来：

npx @playwright/mcp@latest --browser chromium

如果终端里能看到 MCP Server 的启动日志，并且进程不退出，就说明环境没问题。等看到类似“MCP server running”的提示后，按Ctrl+C结束，再去配置 Claude Code。这样能快速把问题限定在“环境”还是“配置”上。

6. 最后说几句个人体会

这套东西在 Windows 下配置确实比 macOS 麻烦，但基本都是一次性成本。只要环境变量、浏览器内核、参数格式这三个点打通了，后面用起来会非常顺手。我现在做页面自动化测试已经尽量不用大量手写脚本，而是直接在 Claude Code 里描述“我要什么效果”，模型自己操作浏览器去实现。

基于我这几天的实际使用，有两点想补充一下。一是不要一上来就加一堆自定义参数，MCP Server 用默认配置跑通之后，再按需添加--headed、--viewport-size这些选项，排查问题会清晰很多。二是如果你的使用场景是登录态操作，记得用--isolated false复用系统浏览器，否则每次会话都要重新登录，体验会很割裂。

再分享一个小技巧：在claude mcp list输出正常之后，先让它打开一个本地页面，比如http://localhost:3000（如果本地有开发服务），确认内网页面能打开；然后再尝试外网页面。这样哪怕后面出了问题，你也大概知道是页面本身的问题，还是浏览器操作链路的问题。

如果你在 Windows 上配置 Playwright MCP 时遇到了和我不同的报错，欢迎把报错信息发出来一起讨论。工具链这种东西，一个人踩坑效率太低，多交流几次就能把潜在的坑提前绕开了。