企业官网建设流程全解析

最近在 Windows 上折腾 Claude Code，想把 Playwright 接成 MCP 工具，这样在终端里就能让 AI 帮我打开浏览器、点点页面、截图回传。前后折腾了两个晚上，踩了三个跟 Windows 环境密切相关的坑，今天把整个过程、报错原文、解决办法一次说清楚。如果你也在 Windows 上配置 Claude Code 和 Playwright MCP，这篇文章应该能帮你少走我这些弯路。

先说结论：Claude Code 本身很好装，真正让人头疼的是后面的 MCP 配置——不是概念难，而是 Windows 这台“老爷车”到处都是历史包袱。这篇文章我会按“先把概念捋清楚 → 环境准备 → 三个坑逐条复盘 → 抄作业配置 → 实际体验 → 问题排查”的顺序来讲。无论你是第一次听说 MCP，还是已经在用但被配置搞到怀疑人生，都能从中找到对应的答案。

1. 先把概念捋清楚：Claude Code、MCP、Playwright 分别是什么

1.1 Claude Code 是什么，它和普通聊天 AI 有什么不一样

Claude Code 是 Anthropic 推出的终端版 AI 编程助手。它跑在命令行里，不是网页对话框那种一问一答的形式，而是直接“住在”你的项目目录里，能读取项目文件、修改代码、执行命令、跑测试，再把结果反馈给你。

我最初用它，是因为不想在浏览器和终端之间来回切换。你直接把需求用自然语言写给它，比如“帮我看看这个模块为什么编译报错”，它会自己去翻代码、定位问题，然后给出修改建议。这种“代理式”的工作方式，比单纯的代码补全更适合处理真实项目里的跨文件问题。

但 Claude Code 有一个明显的边界：它默认只能操作文件系统和命令行，碰不到浏览器。想让 AI 帮你去实际打开一个网页、点击按钮、看看页面渲染效果，它做不到。这时候就需要给 Claude Code 接上一个“浏览器工具”——Playwright MCP 就是干这个的。

1.2 MCP 协议到底是干嘛的，用 USB-C 类比一下就懂了

MCP 全称 Model Context Protocol，可以理解为“AI 应用的 USB-C 接口”。在没有 USB-C 之前，每个设备都有自己的充电口，你得准备一堆线；有了统一接口之后，一根线通吃。

MCP 解决的是同一个问题：让 AI 应用能通过一套标准协议，接入各种各样外部工具和数据源。以前你要给 AI 加一个浏览器能力，得单独写一套接口；加一个数据库能力，又要写一套。现在只要这些工具都做成 MCP Server，AI 这边作为 MCP Host，就能用统一的方式去调用它们。

所以在这个场景里，Claude Code 是 MCP Host，负责调度和对话；Playwright MCP 是 MCP Server，负责提供浏览器自动化能力。两者之间通过 MCP 协议通信，Claude Code 说“帮我把这个页面截图”，Playwright MCP 就去操作浏览器，再把结果返回给 Claude Code。配置 MCP 的过程，本质上就是把“这个 Server 在哪儿、怎么启动、叫什么名字”告诉 Host。

1.3 为什么偏偏是 Windows 上容易出问题

我平时主力机就是 Windows，折腾完这一趟，最大的感受是：很多教程默认在 macOS 或 Linux 上写，到了 Windows 全变样，而且没人告诉你哪些会变。

具体来说有三个原因。第一，Windows 的命令行环境是 PowerShell 和 CMD，跟 Linux 的 bash 行为差异很大，很多命令写法不一样，比如路径分隔符是反斜杠，环境变量用 %VAR% 或者 $env:VAR，脚本类型的文件还要考虑.cmd后缀的问题。第二，npm 生态在 Windows 上的历史问题不少，全局安装后的命令经常因为 PATH 没配好而找不到。第三，Windows 上路径容易带空格和中文，而这恰好是很多命令行工具最不喜欢碰到的两样东西。

后面这三个坑，每一个都直接踩在 Windows 的这些特殊脾气上。

2. 环境准备：先把这三样东西凑齐，后面才好办事

2.1 安装 Claude Code：先检查 Node.js，再装全局包

Claude Code 是 npm 包，安装前需要 Node.js。官方要求 Node 18 以上，我的经验是直接上 Node 20+，版本太老容易出现兼容问题。Windows 下管理 Node 版本，我推荐先装 nvm-windows，这样以后想换版本随时切，不用重新下载安装包。

装好 Node 之后，打开 PowerShell，执行下面这行命令：

npm install -g @anthropic-ai/claude-code

安装完成后，验证一下：

claude --version

我第一次执行到这里，就踩了坑一：提示“claude 不是内部或外部命令”。这个问题我放在第三章详细讲，这里先记住，如果看到这个报错，先别怀疑安装有问题，大概率是 PATH 的锅。

第一次运行claude，它会提示你登录账号，按提示在浏览器里完成授权就行。这个过程和正常使用 AI 产品是一样的，登录后就能进入交互界面。

2.2 安装 Playwright MCP：选官方 npm 包还是 Python 包

Playwright MCP 是微软团队开源的，仓库名是 microsoft/playwright-mcp。它提供了两种使用方式，一种是 npm 包@playwright/mcp，通过npx启动；另一种是 Python 包playwright-mcp，通过python -m playwright_mcp启动。两者功能基本等价，选哪个取决于你的技术栈。

我这次用的是 npm 版本，因为 Node 环境是现成的，配置起来少一层依赖。安装命令：

npm install -g @playwright/mcp

这里有朋友会问：为什么不直接npx @playwright/mcp临时拉取，非要全局装？我的理由是，全局安装之后版本相对固定，启动速度更快，而且排错时能少一个“下载会不会超时”的变量。如果你喜欢保持干净，也可以不装，直接在配置里用-y参数临时拉取，后面我会给出两种配置写法。

2.3 安装浏览器内核：Playwright 不是直接调 Chrome

Playwright 和很多自动化工具一样，不是直接驱动你日常用的那个 Chrome，而是会下载一套它自己管理的浏览器内核，放在系统缓存目录下。Windows 上默认位置是C:\Users\你的用户名\AppData\Local\ms-playwright。

安装内核的命令：

npx playwright install chromium

这行命令会下载 Chromium 对应的浏览器文件。很多人在这里卡住，下载速度极慢或者直接失败。如果你在下载这一步遇到问题，先别慌，坑二里有解决方案。

这里有个小提醒：如果你日常用的是 Chrome 或 Edge，并且不想额外下载浏览器，Playwright MCP 也支持连接现有的 Chrome 实例，启动参数里带个--channel chrome就能指定。但对于大多数场景，我还是建议直接下载它自带的 Chromium，省得版本不匹配。

2.4 装完以后，先做两个 Windows 专属的前置检查

进入配置阶段之前，我强烈建议先做两个检查，能帮你排除掉一大半后续的“玄学问题”。

第一个是检查命令是否都在 PATH 里。在 PowerShell 里依次执行：

where.exe claude where.exe npx

如果都能返回路径，说明 PATH 没问题。如果其中任何一个提示找不到，就先解决路径问题，再继续往下走。第二个是检查 PowerShell 执行策略：

Get-ExecutionPolicy

如果返回结果是Restricted，说明当前环境禁止执行脚本文件，后面 npx 可能也会遇到麻烦。可以临时放开：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这个设置只影响当前用户，不会动系统级别的安全策略，可以放心。

3. 三个坑的完整复盘：报错原文、原因分析、解决办法

3.1 坑一：Claude Code 明明装好了，claude 命令却“不翼而飞”

安装过程一切正常，npm 也输出了成功日志，但我在 PowerShell 里敲claude --version，直接给我来了一句：

claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

第一次遇到这个问题，我心里第一反应是“装了个寂寞”，然后去翻 npm 的日志，发现确实是装好了的。那问题出在哪？

原因在 npm 的全局安装目录。npm 把全局可执行文件放在一个 bin 目录里，这个目录通常长这样：C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录没有被加进系统 PATH，你运行claude时，Windows 根本不知道去哪儿找它。

解决办法有两个，选一个顺手就行。第一个是手动把 npm 全局目录加进 PATH：

1. 在 PowerShell 里执行npm config get prefix，拿到 npm 的全局根目录；
2. 打开系统环境变量设置（Win + R 输入sysdm.cpl，或者直接在“设置”里搜“环境变量”）；
3. 在用户 PATH 里追加%prefix%\bin，这里的 prefix 就是上一步拿到的路径；
4. 保存后重开 PowerShell 终端，再运行claude --version。

第二个办法更省事，直接重新运行 Node.js 安装包，安装过程中勾选“Add to PATH”选项，让安装器帮你把缺失的路径补全。不过这个方法需要重新装一遍 Node，适合顺手解决，不适合已经用了很久 nvm 的情况。

这个坑给我的教训是：在 Windows 上装完任何 npm 全局工具，第一件事就是跑一遍where命令确认命令能查到，不要想当然。

3.2 坑二：Playwright 浏览器内核下载超时，卡了半小时

装完@playwright/mcp之后，我执行npx playwright install chromium，下载进度条一直走走停停，速度只有几十 KB/s，等了一会儿直接报：

ETIMEDOUT

这就是坑二，也是网上问得最多的问题。Playwright 下载浏览器内核时，默认去的是官方下载地址，这个源在国内访问经常超时。注意，这跟你的网络环境没关系，纯粹是线路响应慢的问题，别急着关防火墙、改 DNS，先试镜像源。

解决办法是设置一个环境变量，把下载地址指到国内镜像：

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

如果你想让这个环境变量长期生效，可以按 Win + R 输入sysdm.cpl，在“环境变量”里新增一个用户变量，变量名PLAYWRIGHT_DOWNLOAD_HOST，变量值填上面的镜像地址。设置完之后，重新打开终端再执行安装命令。

实测下来，走镜像之后下载速度能提升到几 MB/s，一两分钟就能装完。

这里还有一个后续坑差点坑到我：内核装好后，运行 MCP 时如果弹出“浏览器启动失败”，看看你有没有装杀毒软件。部分杀毒软件会把 Playwright 的浏览器文件当作可疑程序拦截，一旦被隔离，启动就会异常。遇到这种问题，把ms-playwright目录加入白名单就行。

3.3 坑三：MCP 配置写了，Claude Code 里却一直连不上 Playwright

浏览器装好了，PATH 也没问题，接下来就是重头戏：把 Playwright MCP 配置进 Claude Code。

我执行了配置命令：

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

执行完还很得意地验证了一下：

claude mcp list

结果列表里确实有playwright，状态也显示正常。但我在 Claude Code 对话里一让它打开浏览器，立刻就报错：

Playwright MCP server failed to start

这就是坑三，而且这坑的隐蔽程度比前两个高多了。我排查了一圈，最后发现是两个问题叠在一起。

第一个问题是 PowerShell 对@符号的特殊解析。PowerShell 里@playwright/mcp这种写法，有可能会被解析成数组语法或者 splatting，导致传给 npx 的参数不对。解决办法是给包名加引号：

claude mcp add playwright -- npx -y "@playwright/mcp@latest"

第二个问题是 Windows 上用 npx 启动 npm 包时，命令名要写成npx.cmd而不是npx。Claude Code 在 Windows 下启动外部进程时，直接找npx这个可执行文件可能找不到，加了.cmd后缀才能让它正确识别。

这两个问题同时存在，就导致配置表面上成功了，实际运行起来一直失败。最终可行的配置方案我放在第四章，直接照抄就行。

弄完这两个问题，你以为结束了？并没有。改完配置之后，我还发现 Claude Code 输入框下方一直显示找不到 server。最后把终端关掉，重新启动claude，一切才正常。所以记住：在 Windows 上改完 MCP 配置，一定要重启 Claude Code，它不会自动热加载配置文件。

4. 踩完坑后的最终配置方案：抄作业版

4.1 推荐命令：用 claude mcp add 一行搞定

最终稳定可用的添加命令是这样的，直接在项目目录下执行：

claude mcp add playwright --scope project -- npx.cmd -y "@playwright/mcp@latest"

这里的参数我解释一下：--scope project表示这个配置只对当前项目生效，配置文件会写到项目根的.mcp.json里。如果不加这个参数，默认会写到用户级配置里，也就是你所有项目都能用。第一次测试建议用 project 范围，方便以后调整不污染全局。

添加成功后，查看状态：

claude mcp list

你会看到类似这样的输出，playwright这一项是配置名，后面对应的是启动命令。注意，这里的status列显示的 connected 不代表真的能跑，只是表示配置本身能被识别，真正的联通测试要看下面第四章第三小节。

4.2 手工修改配置文件：适合需要微调参数的场景

如果你不喜欢命令行添加，也可以直接编辑配置文件。项目级配置写在项目根目录的.mcp.json：

{ "mcpServers": { "playwright": { "command": "npx.cmd", "args": ["-y", "@playwright/mcp@latest"] } } }

用户级配置则写在~/.claude.json里，路径在C:\Users\你的用户名\.claude.json，格式是一样的，只是位置不同。我个人的实践是：项目级配置优先，因为同一个项目换机器、换人接手，.mcp.json一拷过去就带走了，体验很顺。

这里有个 Windows 专属的小细节：JSON 文件里的command字段，一定要写npx.cmd而不是npx。写npx在 macOS 上没问题，但在 Windows 上就等着报错。此外，如果args里要传路径，注意反斜杠要写成双反斜杠转义，比如"C:\\path\\to\\script.js"。

4.3 验证配置是否真的通：别只看列表状态

配置完，我建议按下面这套流程验证，一步到位，避免“以为配好了，实际跑不起来”的尴尬。

第一步，在项目目录执行：

claude mcp list

确认配置存在。第二步，用 inspect 命令看看 server 本身能不能被启动：

claude mcp inspect playwright

这个命令会尝试启动 Playwright MCP server，并把服务器端返回的日志打印出来。如果它正常启动并输出了 MCP 的连接信息，说明 server 本身没问题。如果启动失败，会直接告诉你报错原因，省去在对话里反复试错的时间。

第三步，也是最直观的验证方式：启动claude，在对话里输入：

用 Playwright 打开 example.com，把页面截图保存到 D:\temp\page.png

如果一切正常，你会看到 Claude Code 给出“正在调用 playwright 工具”之类的提示，然后一个浏览器窗口短暂弹出又关闭，最后返回截图文件路径。到这一步，整个配置才算真正完成。

5. Playwright MCP 在实际使用中的效果和边界

5.1 用自然语言操作浏览器，实际体验怎么样

配置完成后，我试用了一周，说几个实际场景，让没装过的人感受一下这东西到底能干嘛。

第一个场景是页面冒烟测试。我本地起了个前端项目，直接跟 Claude Code 说：“打开 localhost:3000，登录页面应该有个用户名输入框，帮我看看这个页面渲染有没有报错。”它会自己导航到页面，读取页面快照，截图回传，然后告诉你页面结构、有没有报错信息。整个过程不需要我手写任何 Playwright 代码。

第二个场景是填表单。有些后台系统测试需要反复填同一套数据，以前我得写脚本，现在直接说“在搜索框输入‘测试订单’，点击查询按钮，把结果截图给我”，它就能完成。

我观察到的技术原理是这样的：Playwright MCP 不是靠“看截图”来理解页面的，它会给 Claude Code 返回一个可访问性快照（accessibility snapshot），把页面里的可交互元素用树状结构描述出来。AI 根据这棵树决定下一步点哪里、输入什么，而不是靠视觉猜。这也是为什么它在处理表单、按钮这类结构清晰的页面时，准确率还不错。

5.2 适合做什么、不适合做什么：先说清楚边界

用了一周，我把 Playwright MCP 的适用范围划分得很明确。

适合做的：探索式测试、快速页面验证、填表单、截图取证、调试本地页面。这类任务的特点是“你只需要一个结果，不关心过程细节”，用自然语言描述给 AI 是最顺的。

不太适合的：需要严格断言的端到端测试、需要频繁稳定执行的回归用例。原因很简单，大模型操作浏览器天然存在不确定性，同样的 prompt 可能这次点这里、下次点那里，在需要精确控制每一步的自动化测试体系里，这不可接受。真要建回归用例，还是用 Playwright 原生脚本写比较稳。

还有个实践心得：Claude Code 调用浏览器操作时，建议把任务拆细一点。一次只说一件事，比如“打开页面”是一步，“截图”是另一步，不要让 AI 一口气执行十步操作。不是它做不到，而是链路越长，中间出现一点偏差后，AI 需要花更多精力去纠正，效率反而下降。

5.3 如果以后想接更多工具，套路是一样的

配置好 Playwright MCP 之后，你会发现自己突然懂了整个 MCP 生态的用法。数据库 MCP、文件系统 MCP、设计稿 MCP，本质都是同一个流程：装 Server → 配置命令 → 重启 Host → 验证连通。你在 Windows 上踩过的这些坑，在接下一个工具时大概率还会碰到，但你已经知道从哪几个方向排查了。

6. 常见问题与排查技巧速查表

6.1 高频问题对照表

这一章把 Windows 上常见的报错和解决办法整理成一张表，方便你对照排查。

6.2 我排查 MCP 问题时的通用思路

最后分享一个方法论，这个比任何具体命令都值钱。

遇到“MCP 连接不上”这类问题，先判断是哪一层的锅。第一层是工具本身能不能启动，第二层是 Claude Code 能不能正确调用它。怎么区分？直接在终端手动运行一遍启动命令。比如我们的场景，手动执行：

npx.cmd -y "@playwright/mcp@latest"

如果这条命令能正常启动，并且终端里出现类似“MCP server running”的提示，说明 Server 本身没问题，问题出在 Claude Code 和 Server 之间的通信上，继续查配置文件的 command、args、路径。如果这条命令本身就报错，那就先解决 Server 自身的问题，不要急着去改 Claude Code 的配置。

这个思路适用于所有的 MCP 工具，不只是 Playwright。把问题先定位到具体环节，你就不会再被一长串看不懂的报错带着跑了。

另外我还想强调一下版本问题。这类工具迭代很快，我在网上搜到的很多教程，报错信息在我这个版本已经不适用了，或者给出的配置方式在新版本里已经变了。遇到诡异问题，先升级 Node、Claude Code、Playwright MCP 到最新版，再重新配置一遍，很多“玄学”问题会自动消失。

我个人在实际操作中的体会是：配置这类东西，一半的坑其实是信息差——教程是旧版本写的、系统是 macOS、终端是 zsh，这些差异叠加在 Windows 上就成了天坑。所以不管看到哪篇教程，都要带着“这玩意儿在 Windows 上可能不一样”的心态去对照。现在 Playwright MCP 已经跑在我日常的工作流里，每次只要一句话就能自动打开浏览器、填表、截图，确实省了不少重复劳动。最后再叮嘱一句：在 Windows 上折腾这类工具，先检查 PATH，再怀疑网络，然后看 JSON，大部分问题都藏在这三件事里。