Playwright MCP 自动化项目实战：从能跑到好用的工程化指南

1. 为什么大多数自动化项目活不过第三周

我见过太多自动化项目死在同一个地方：第一周跑通了登录，第二周加上了截图，第三周没人再打开过那个仓库。问题不在于技术选型，而在于从第一天起，这个项目就被定位成了"演示品"而不是"生产工具"。

Playwright MCP 这个组合之所以值得认真对待，是因为它把浏览器自动化的控制权从"写死的脚本"转移到了"可对话的智能体"手里。传统方案里，你写page.click('#submit')，选择器一变就全盘崩溃；而 MCP 模式下，模型可以理解页面语义、动态决策下一步动作。这不是简单的工具替换，而是自动化范式的迁移。

但范式迁移也意味着，如果你还用写 Demo 的思路去做，结果只会是一个更花哨的 Demo。真正让项目活下来的，是把它当成一个有输入、有输出、有错误处理、有监控、有迭代节奏的产品来对待。这篇文章要讲的，就是怎么跨过那条从"能跑"到"能用"的鸿沟。

适合读这篇的人：已经跑通过 Playwright 基础脚本、听说过 MCP 协议、但不确定怎么把两者组合成可持续项目的开发者。如果你还在纠结要不要学 Playwright，那这篇可能节奏偏快，但里面的架构思路对任何自动化项目都通用。

2. 先搞清楚 MCP 到底替 Playwright 解决了什么

2.1 传统 Playwright 脚本的三个死穴

写 Playwright 脚本的人迟早会撞上这三堵墙。

第一堵墙是选择器脆弱性。你精心挑选的#app > div.main > form > button:nth-child(3)，前端改一次布局就废了。用getByRole('button', { name: '提交' })好一些，但页面文案一改又得跟着改。本质上，脚本把"意图"和"实现"绑死了。

第二堵墙是流程刚性。脚本假设页面永远按 A→B→C 的顺序走。一旦出现弹窗、验证码、加载延迟、A/B 测试分支，脚本就卡死。你只能不断加waitFor和if判断，最后脚本变成一团面条。

第三堵墙是维护成本随场景线性增长。支持 10 个页面要写 10 套逻辑，支持 100 个页面就是灾难。因为每个场景都是独立硬编码的，没有抽象层。

2.2 MCP 带来的本质变化

MCP（Model Context Protocol）的核心价值，是给模型提供了一个标准化的工具调用接口。在 Playwright MCP 的场景里，浏览器被封装成一组工具：导航、点击、输入、截图、读取页面结构、执行 JS。模型不再需要预先知道"第几步点哪个按钮"，而是根据当前页面状态和任务目标，动态决定调用哪个工具。

这个变化带来的直接好处是：意图和实现解耦了。你告诉系统"帮我把购物车里的商品结算"，模型自己去看页面、找按钮、处理弹窗。选择器变了？模型重新识别就行。流程有分支？模型根据实际情况判断。

但这里有个关键认知：MCP 不是让 Playwright 变得"智能"，而是让控制流从脚本转移到了模型。Playwright 依然是那个可靠的执行引擎，MCP 是模型和引擎之间的翻译层。理解这一点，才能设计出合理的架构。

2.3 什么场景适合，什么场景别硬上

不是所有自动化都适合 MCP 模式。我踩过的坑告诉我，判断标准很简单：

举个例子：每天定时抓取固定报表，页面三年没变过，这种用传统脚本又快又稳，上 MCP 是杀鸡用牛刀。但如果是"帮用户在多个电商平台比价并下单"，页面千变万化，MCP 模式的优势就出来了。

注意：MCP 模式引入了模型推理环节，每次操作都有额外的 token 消耗和延迟。如果你的场景是每秒要执行几十次点击，MCP 会成为瓶颈。它适合的是"低频、高复杂度、需要决策"的任务。

3. 项目骨架：从第一天就按生产标准搭

3.1 目录结构决定项目能活多久

我见过太多项目把所有逻辑塞进一个index.js，跑到 500 行就开始失控。Playwright MCP 项目从一开始就要分层。下面是我实际用下来最顺手的结构：

project/ ├── src/ │ ├── mcp/ │ │ ├── server.ts # MCP 服务入口，注册工具 │ │ ├── tools/ # 每个浏览器能力封装成独立工具 │ │ │ ├── navigate.ts │ │ │ ├── interact.ts │ │ │ └── extract.ts │ │ └── context.ts # 会话上下文管理 │ ├── browser/ │ │ ├── pool.ts # 浏览器实例池 │ │ └── lifecycle.ts # 启动、复用、销毁逻辑 │ ├── tasks/ │ │ ├── definitions/ # 任务定义（YAML 或 TS） │ │ └── runner.ts # 任务执行器 │ └── observability/ │ ├── logger.ts │ └── metrics.ts ├── config/ │ ├── default.yaml │ └── environments/ └── tests/ ├── unit/ └── e2e/

这个结构的关键在于：MCP 工具层、浏览器管理层、任务层、可观测层完全分离。工具层只负责"能做什么"，任务层负责"要做什么"，中间通过上下文传递状态。这样当你要换模型、换浏览器、换任务定义方式时，改动被限制在单层内。

3.2 浏览器实例池：别每次任务都冷启动

新手最常见的性能问题：每个任务启动一个新浏览器。Chromium 冷启动大概 1-2 秒，加上页面加载，一个简单任务要 5 秒以上。如果一天跑几百个任务，光启动开销就吃掉大量时间。

正确做法是维护一个浏览器实例池。核心逻辑：

// browser/pool.ts 的核心思路 class BrowserPool { private available: BrowserContext[] = []; private maxSize: number; async acquire(): Promise<BrowserContext> { if (this.available.length > 0) { return this.available.pop()!; } if (this.currentSize < this.maxSize) { return await this.createContext(); } return await this.waitForRelease(); } async release(ctx: BrowserContext) { // 清理 cookies、localStorage，重置到干净状态 await ctx.clearCookies(); await ctx.clearPermissions(); this.available.push(ctx); } }

这里有个容易忽略的细节：释放时必须清理上下文状态。否则上一个任务的登录态、缓存会污染下一个任务。我早期就因为这个 bug，导致任务 A 的登录信息泄漏到任务 B，排查了半天。

池的大小怎么定？经验值是 CPU 核心数的 1.5 到 2 倍。8 核机器开 12-16 个 context 比较合适。但要注意，每个 context 都占内存，Chromium 单 context 大概 50-100MB，开太多会 OOM。监控内存使用，动态调整。

3.3 配置外置：别把环境信息写进代码

我见过最离谱的代码是把目标 URL、账号、超时时间全硬编码在脚本里。换一个环境就要改代码、重新部署。正确做法是所有环境相关的配置外置到 YAML：

# config/default.yaml browser: headless: true timeout: 30000 pool_size: 12 viewport: width: 1440 height: 900 mcp: max_steps: 50 retry_on_failure: 2 screenshot_on_error: true tasks: default_timeout: 120000 max_concurrent: 4

然后在代码里用配置加载器读取，支持环境变量覆盖。这样本地开发、测试环境、生产环境用同一套代码，只是配置不同。部署时改配置不改代码，这是生产项目的基本素养。

4. MCP 工具设计：粒度比数量重要

4.1 工具粒度太细会让模型迷路

刚开始做的时候，我恨不得把 Playwright 的每个 API 都封装成一个 MCP 工具：click、fill、hover、scroll、press、select……结果模型面对几十个工具，经常选错，或者一个简单操作要调用七八次工具。

后来我意识到，工具设计要匹配模型的认知粒度，而不是 API 的粒度。模型理解的是"在搜索框输入关键词并提交"，而不是"先 click 输入框，再 fill 文本，再 press Enter"。所以工具应该按用户意图来划分，而不是按底层 API。

调整后的工具集大概是这样：

工具数量控制在 6-10 个，每个工具的职责边界清晰。模型调用时不需要纠结"该用 click 还是 tap"，只需要表达意图。

4.2 每个工具都要有"失败语义"

这是区分 Demo 和生产项目的关键点。Demo 里的工具假设一切顺利，生产里的工具必须处理失败。

以find_and_act为例，它可能失败的原因有：元素不存在、元素存在但不可交互、元素被遮挡、页面还没加载完、有多个匹配元素。每种失败应该返回不同的错误码和上下文信息，让模型能据此决策下一步。

type ActResult = | { status: 'success'; element: ElementInfo } | { status: 'not_found'; candidates: ElementInfo[] } | { status: 'not_interactable'; reason: string } | { status: 'ambiguous'; matches: ElementInfo[] } | { status: 'timeout'; waited_ms: number };

返回not_found时，附带页面上相似元素的列表，模型可以判断是不是选择器写错了。返回ambiguous时，列出所有匹配项，模型可以选择更精确的描述。这种结构化失败让模型有机会自我纠正，而不是直接崩溃。

提示：工具返回的错误信息要包含足够的上下文，但不要塞太多。我试过返回整个 DOM，结果 token 爆炸。返回 top 5 候选元素的简要描述就够了。

4.3 上下文管理：让模型记住"刚才干了什么"

MCP 的每次工具调用是独立的，但任务是有状态的。模型需要知道"我已经登录了""当前在购物车页面""刚才点击失败了三次"。这些信息通过上下文对象传递。

我的做法是维护一个轻量的会话状态：

interface SessionContext { taskId: string; currentUrl: string; history: ActionRecord[]; // 最近 N 步操作 variables: Record<string, any>; // 任务中提取的数据 retryCount: Record<string, number>; // 每个动作的重试次数 }

history只保留最近 10-20 步，避免上下文过长。variables用来在步骤间传递数据，比如第一步提取的订单号，第三步要用。retryCount防止模型陷入死循环——同一个动作失败超过 3 次，就强制中断并上报。

这个设计让我避免了一个经典问题：模型在某个页面上反复点击同一个不存在的按钮，因为每次调用它都"忘记"上次已经失败了。有了 retryCount，第三次失败后系统直接抛出异常，人工介入。

5. 任务编排：把"智能"用在刀刃上

5.1 混合编排：确定性步骤用脚本，不确定性步骤用模型

全用模型决策，成本和延迟都受不了。全用脚本，又失去了灵活性。我的经验是混合编排：把任务拆成步骤，每个步骤标注是"确定性"还是"探索性"。

确定性步骤：登录（固定表单）、导航到已知 URL、提取固定字段。这些用传统 Playwright 代码，快且稳。

探索性步骤：在结果列表中找特定商品、处理未知弹窗、根据页面内容决定下一步。这些交给模型。

# tasks/definitions/price_compare.yaml name: price_compare steps: - id: login type: deterministic action: login_with_credentials params: url: "${env.SITE_URL}" - id: search type: deterministic action: fill_and_submit params: selector: "input[name='q']" value: "${input.keyword}" - id: find_target type: exploratory goal: "在搜索结果中找到价格最低且评分高于4.5的商品" max_steps: 15 - id: extract type: deterministic action: extract_fields params: fields: name: ".product-title" price: ".price-value" rating: ".rating-score"

这样设计的好处是：80% 的步骤是确定性的，跑得快、成本低；20% 的关键决策交给模型，保证灵活性。整体成本比全模型方案低一个数量级。

5.2 任务级重试与断点续跑

生产环境里，任务失败是常态。网络抖动、页面改版、验证码、限流，任何一个都能让任务挂掉。关键是失败后怎么办。

我的方案是任务级检查点。每个步骤完成后，把上下文序列化到存储（Redis 或本地文件）。任务失败时，从最后一个成功的检查点恢复，而不是从头再来。

class TaskRunner { async run(task: Task, input: any) { let checkpoint = await this.loadCheckpoint(task.id); let startStep = checkpoint?.lastCompletedStep ?? 0; for (let i = startStep; i < task.steps.length; i++) { const step = task.steps[i]; try { const result = await this.executeStep(step, checkpoint?.context); checkpoint = { lastCompletedStep: i, context: result.context }; await this.saveCheckpoint(task.id, checkpoint); } catch (err) { if (this.isRetryable(err) && step.retries > 0) { step.retries--; i--; // 重试当前步骤 continue; } throw new TaskFailedError(task.id, i, err); } } } }

这个机制救过我很多次。一个跑 20 分钟的长任务，在第 18 分钟因为网络超时挂了，如果没有检查点，前面 18 分钟白费。有了检查点，重跑只需要 2 分钟。

5.3 并发控制：别让浏览器池被打爆

任务并发数不是越高越好。浏览器池大小、CPU、内存、目标站点的限流策略，都是约束。我的做法是双层限流：

第一层是全局并发上限，等于浏览器池大小。第二层是按目标域名限流，同一个域名同时最多 N 个任务，避免触发反爬。

class ConcurrencyController { private globalSemaphore: Semaphore; private domainSemaphores: Map<string, Semaphore>; async acquire(url: string) { const domain = new URL(url).hostname; const domainSem = this.getOrCreateDomainSemaphore(domain); await domainSem.acquire(); await this.globalSemaphore.acquire(); return () => { this.globalSemaphore.release(); domainSem.release(); }; } }

域名限流的阈值怎么定？保守一点，从 2 开始，观察目标站点的响应时间和错误率，逐步调整。如果出现 429 状态码或响应明显变慢，就降下来。这个没有万能值，得根据实际目标站点试探。

6. 可观测性：没有监控的自动化就是定时炸弹

6.1 结构化日志：出问题时能快速定位

console.log('clicked')在生产环境毫无价值。日志必须是结构化的，包含任务 ID、步骤 ID、时间戳、耗时、结果状态。

logger.info({ event: 'step_completed', taskId: ctx.taskId, stepId: step.id, stepType: step.type, durationMs: Date.now() - startTime, status: 'success', url: ctx.currentUrl, });

这样出问题时，可以按 taskId 过滤出完整执行链路，按 stepType 统计哪类步骤最容易失败，按 durationMs 找出性能瓶颈。日志输出成 JSON 格式，方便接入任何日志系统。

6.2 关键指标：四个数字判断项目健康度

我监控四个核心指标，每天早上扫一眼就知道项目状态：

成功率下降，说明页面改版或目标站点有变化。平均步骤数上升，说明模型在"迷路"，可能需要优化工具设计或提示词。P95 耗时上升，可能是并发太高或目标站点变慢。成本上升，可能是任务复杂度增加或模型陷入循环。

这四个指标配合告警，成功率跌破 90% 就发通知，我基本能在问题扩大前介入。

6.3 失败快照：让排查从小时级降到分钟级

任务失败时，自动保存三样东西：截图、DOM 快照、最近 10 步的操作历史。这三样东西放在一起，基本能还原失败现场。

async function captureFailureArtifacts(ctx: SessionContext, error: Error) { const timestamp = Date.now(); const dir = `failures/${ctx.taskId}_${timestamp}`; await ctx.page.screenshot({ path: `${dir}/screenshot.png`, fullPage: true }); await fs.writeFile(`${dir}/dom.html`, await ctx.page.content()); await fs.writeFile(`${dir}/history.json`, JSON.stringify(ctx.history, null, 2)); await fs.writeFile(`${dir}/error.txt`, error.stack); }

我踩过的坑是：一开始只存截图，结果发现截图上看不出问题（比如元素存在但被透明遮罩挡住），还得手动复现。加上 DOM 快照后，可以直接搜索元素、检查样式，排查效率提升明显。

7. 那些让我熬夜的坑和对应的解法

7.1 模型陷入循环：同一个动作反复失败

这是最常见的坑。模型点击一个按钮，失败，它换个说法再点，再失败，再换……直到 max_steps 耗尽。

根因是模型没有"记忆"到之前的失败。解法是在上下文里显式记录失败历史，并在提示词里强调"如果某个动作失败超过 2 次，尝试完全不同的方法"。

更彻底的解法是动作去重：在工具层拦截，如果检测到连续 3 次调用相同工具且参数相似度超过 90%，直接返回错误并提示模型"你似乎在重复同一个动作，请换一种策略"。

7.2 页面加载时序：waitFor 不够用

Playwright 的waitForLoadState('networkidle')在单页应用里经常不准。页面 DOM 加载完了，但数据还在异步请求，元素还没渲染。

我的解法是双重等待：先等 networkidle，再用waitForSelector等目标元素出现，最后加一个短暂的waitForTimeout(200)让渲染稳定。这个 200ms 看起来是"魔法数字"，但实测下来能避免大量偶发的元素不可交互问题。

更好的做法是让模型自己判断：工具返回"元素存在但不可交互"时，模型可以选择等待后重试。但这会增加 token 消耗，需要权衡。

7.3 验证码和反爬：别硬刚，要绕

自动化项目迟早会遇到验证码。我的原则是：不破解，只规避和上报。

规避策略：控制请求频率、模拟真实用户行为（随机延迟、鼠标移动轨迹）、使用真实的 User-Agent 和视口尺寸。

上报策略：检测到验证码时，立即暂停任务，保存现场，通知人工处理。人工处理后，从检查点恢复。

硬刚验证码的代价太高，而且不稳定。把精力放在业务逻辑上，验证码这种问题用人工兜底更划算。

7.4 内存泄漏：跑久了就 OOM

长时间运行的项目，内存会缓慢增长。根因通常是：页面对象没释放、事件监听器没移除、上下文没清理。

我的解法是定期重启浏览器实例。每个 context 使用超过 100 次或运行超过 1 小时，就销毁重建。虽然损失一点启动开销，但避免了内存泄漏累积。

同时，在释放 context 时，显式移除所有监听器：

async function cleanupContext(ctx: BrowserContext) { ctx.removeAllListeners(); await ctx.clearCookies(); await ctx.clearPermissions(); await ctx.close(); }

8. 从能跑到好用：迭代节奏怎么把握

8.1 第一周：只做一件事，但做透

别一上来就设计大而全的系统。第一周只做一件事：让一个最简单的任务端到端跑通，并且有日志、有失败快照、有重试。

比如"登录并提取用户信息"这一个任务。把它跑通，跑稳，跑 100 次成功率 99%。这个过程会让你把 MCP 工具设计、上下文管理、错误处理、日志这些基础设施都摸一遍。基础设施稳了，后面加任务就是复制粘贴。

8.2 第二到四周：按任务类型扩展

基础设施稳了之后，开始加任务。但不要一个一个加，要按类型加。比如先加"表单填写类"任务，把这类任务的共性抽象出来；再加"列表提取类"任务，抽象出分页、滚动加载的处理逻辑。

每加一类任务，回头看看工具设计是否需要调整。如果发现某类任务总是需要模型做同样的决策，就把它下沉成确定性步骤或新工具。

8.3 一个月后：优化成本和速度

项目稳定运行一个月后，开始优化。这时候你有了真实数据：哪些任务最耗时、哪些步骤最容易失败、token 消耗分布如何。

优化方向：把高频的探索性步骤转成确定性步骤（用模型跑 100 次总结出规律，然后写成脚本）、合并冗余的工具调用、调整并发参数、优化提示词减少 token 消耗。

我做过一次优化，把某个任务的 token 消耗从平均 8000 降到 2500，方法就是把模型决策的 5 个步骤中的 3 个改成了确定性脚本。速度提升 3 倍，成本降 70%。

8.4 持续迭代：把每次失败变成改进

最后也是最重要的：建立失败复盘机制。每周花半小时看失败日志，找出 top 3 失败原因，针对性地改进。

失败原因通常分三类：页面变化（更新选择器或让模型更鲁棒）、系统问题（修 bug 或调参数）、目标站点策略（调整频率或换方案）。每类都有对应的解法，关键是别让同样的失败重复发生。

我维护一个"已知问题"文档，每次失败复盘后更新。新任务开发前先看这个文档，避免踩已知的坑。这个习惯让项目的稳定性随时间提升，而不是随时间腐化。

自动化项目能不能活下来，不取决于技术多先进，而取决于你有没有把它当成一个需要持续照料的产品。Playwright MCP 给了你一个强大的起点，但后面的路，得靠工程化的耐心一步步走。