企业官网建设流程全解析

1. 为什么 Cursor + Playwright MCP 能解决元素定位的老大难

UI 自动化最让人头疼的从来不是写断言，而是元素定位。页面结构一改，昨天还能跑的脚本今天就报TimeoutError；一个按钮没有 id、没有 name，只能靠一长串 XPath 硬撑，维护成本高得离谱。传统做法是打开 DevTools 一层层扒 DOM，找到相对稳定的属性再手写 locator，一个页面十几个元素，半天就没了。

Cursor 是一个类 VSCode 的智能编程 IDE，内置了大语言模型，支持自然语言编程和代码重构。Playwright MCP 则是基于 Model Context Protocol 的浏览器自动化服务器，它把 Playwright 的浏览器控制能力通过结构化命令暴露给 LLM，核心依赖浏览器的可访问性树（Accessibility Tree）而不是视觉模型。两者结合后，你可以在 Cursor 的对话里用自然语言描述"点击登录按钮"，MCP 会实时读取页面结构，返回语义化的定位建议，甚至直接帮你把 locator 写进代码文件。

这套组合适合谁？测试工程师想把手工用例快速转成自动化脚本、前端想在重构后快速回归关键路径、或者任何被 XPath 折磨过的开发者。目标很明确：让 AI 帮你完成从"看到页面"到"定位元素"再到"生成可执行用例"的最小闭环。下面我把 config.toml 骨架、Cursor 的 MCP 配置片段、以及一次完整的元素定位验证动作拆开讲，照着做就能跑通。

2. 前置准备：TaoToken 接入与 Playwright MCP 环境

在配置 MCP 之前，先解决模型调用的问题。Cursor 本身可以接自己的模型，但如果你想让 MCP 的调用链路更稳定、成本更可控，建议通过 TaoToken 来统一管理 API Key。TaoToken 提供兼容 OpenAI 风格的接口，配置简单，适合在 Cursor 里作为自定义模型端点使用。

你需要先拿到一个 API Key。访问 https://taotoken.net/api-keys 创建密钥，然后在 Cursor 的模型设置里填入。TaoToken 的 API 地址是 https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base_url 使用即可。如果你对模型对话能力还不熟悉，可以先到 https://taotoken.net/models 体验一下，确认模型能正常响应后再接入 Cursor。

环境侧需要准备两样东西：Node.js（建议 18 以上）和 Playwright 的浏览器依赖。Playwright MCP 本质上是一个 Node 服务，通过 stdio 和 Cursor 通信。安装命令如下：

npm install -g @playwright/mcp npx playwright install chromium

第一条命令全局安装 MCP 服务，第二条确保 Chromium 内核就位。如果你之前装过 Playwright，这一步可以跳过。装完后用npx @playwright/mcp --version验证一下，能输出版本号就说明环境没问题。

注意：Playwright MCP 默认使用 Chromium，如果你需要测试其他内核，可以在启动参数里指定--browser firefox或--browser webkit，但对应的浏览器依赖也要提前装好。

3. 可复制的 config.toml 骨架与 Cursor MCP 配置

Cursor 的 MCP 配置有两种方式：一种是在项目根目录建.cursor/mcp.json，另一种是全局配置。这里我推荐项目级配置，方便团队共享。但既然标题提到 config.toml，我先给一份通用的 TOML 骨架，你可以把它放在项目config/目录下，作为 MCP 启动参数的集中管理文件。

# config/mcp_config.toml [mcp] name = "playwright" command = "npx" args = ["@playwright/mcp@latest", "--headless", "--isolated"] [mcp.env] PLAYWRIGHT_HEADLESS = "true" PLAYWRIGHT_TIMEOUT = "30000" [browser] viewport_width = 1440 viewport_height = 900 user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" [locator] priority = ["role", "label", "placeholder", "text", "alt", "title", "xpath", "css"]

这份 TOML 不是 Cursor 直接读取的，而是给你自己看的"参数源"。真正生效的是 Cursor 的 MCP 配置文件。在项目根目录创建.cursor/mcp.json，内容如下：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--headless", "--isolated"], "env": { "PLAYWRIGHT_HEADLESS": "true", "PLAYWRIGHT_TIMEOUT": "30000" } } } }

保存后重启 Cursor，在设置里的 MCP 面板应该能看到playwright服务处于 running 状态。如果显示 failed，先检查npx是否在 PATH 里，再确认 Node 版本。--isolated参数的作用是每次启动用全新的浏览器上下文，避免缓存干扰定位结果，调试阶段建议保留。

接下来把 TaoToken 的模型接入 Cursor。在 Cursor 设置里找到 Models，添加自定义模型，Base URL 填https://taotoken.net/api，API Key 填你刚才创建的密钥，模型名按 TaoToken 文档里支持的填写。配置完成后在对话里发一句"你好"，确认模型能正常回复。

4. 验证请求：从元素定位到用例执行的最小链路

环境配好后，我们来跑一次完整的验证。假设你要测试一个登录页面，目标是定位用户名输入框、密码输入框和登录按钮，然后生成一个可执行的 Playwright 脚本。

第一步，在 Cursor 对话里输入：

请用 Playwright MCP 打开 https://example.com/login，分析页面可访问性树， 找出用户名输入框、密码输入框、登录按钮的语义化定位方式， 按 role > label > placeholder > text 的优先级给出 locator。

MCP 会启动浏览器、访问页面、读取可访问性树，然后返回类似这样的结果：

用户名输入框：page.get_by_label("用户名") 密码输入框：page.get_by_label("密码") 登录按钮：page.get_by_role("button", name="登录")

第二步，让 AI 把定位写进你的项目结构。假设你的项目有locators/login_locators.py，直接说：

把上面三个定位写入 locators/login_locators.py， 用类属性封装，命名遵循 login_username_input、login_password_input、login_submit_btn。

AI 会生成类似这样的代码：

# locators/login_locators.py class LoginLocators: login_username_input = ("label", "用户名") login_password_input = ("label", "密码") login_submit_btn = ("role", "button", "登录")

第三步，生成页面操作层和测试用例。继续在对话里说：

在 pages/login_page.py 里封装 login 方法， 接收 username 和 password，调用上面的 locator 完成登录。 然后在 testcases/test_login.py 里写一个测试用例， 用已知账号 admin/123456 登录，断言登录后 URL 包含 /dashboard。

AI 会补全login_page.py和test_login.py。最后你直接运行：

pytest testcases/test_login.py -v

如果一切正常，你会看到测试通过，浏览器自动完成登录并跳转。整个过程你只输入了自然语言，没有手写一行 locator。这就是 Cursor + Playwright MCP 的最小闭环：描述需求 → MCP 读取页面 → AI 生成代码 → 执行验证。

提示：第一次跑的时候建议加--headed参数，肉眼确认浏览器操作是否符合预期。稳定后再切回 headless 模式。

5. 本篇常见错排查

MCP 服务启动失败，Cursor 里显示红色。最常见的原因是npx路径问题。在终端里执行which npx，把绝对路径填到mcp.json的command字段里。Windows 下可能是npx.cmd，注意后缀。

定位返回空结果或超时。检查页面是否需要登录才能访问。Playwright MCP 启动的是全新上下文，没有你的登录态。解决办法是在对话里先让 MCP 执行登录动作，再分析目标页面。或者用--storage-state参数加载已保存的登录状态。

AI 生成的 locator 用了 XPath 而不是语义化定位。这通常是因为页面可访问性树不完整，比如按钮没有role或name。这时候需要在对话里明确要求："如果语义化定位不可用，请说明原因，并给出备选方案。" 同时检查你的.cursor/rules里有没有写定位优先级规则，没有的话 AI 会自由发挥。

TaoToken 接口返回 401 或 404。确认 Base URL 是https://taotoken.net/api，不要多加/v1或斜杠。API Key 是否复制完整，有没有多余空格。如果还是不通，到 https://taotoken.net/doc 对照文档检查请求格式。

测试执行时元素找到了但点击无效。可能是元素被遮挡或还没渲染完。在 locator 后面加.wait_for(state="visible")，或者用page.wait_for_load_state("networkidle")等页面稳定。Playwright MCP 返回的定位是静态分析结果，实际执行时仍需考虑动态加载。

6. 把 MCP 用进日常编码流

跑通最小链路后，你可以把这套流程固化到项目里。我的做法是在.cursor/rules下放三个 mdc 文件：一个管代码风格，一个管任务拆解，一个专门管 UI 自动化定位优先级。这样每次让 AI 写代码，它都会先复述需求、列出待办、按 role > label > placeholder 的顺序选定位方式，不会乱改核心模块。

如果你需要长期做编码和 Agent 任务，可以考虑 TaoToken 的 Coding Plan，地址是 https://taotoken.net/coding-plan，适合高频调用场景。日常调试模型能力的话，直接到 https://taotoken.net/models 对话验证就行。接入文档在 https://taotoken.net/doc，API Key 管理在 https://taotoken.net/api-keys，按需取用。

下一步可以尝试把手工测试用例写成 Excel，让 AI 读取表格批量生成 testcases 下的脚本，真正实现零代码写 UI 自动化。这个方向我还在试，等跑顺了再单独写一篇。