浏览器自动化失败时，日志里经常只有一句：

TimeoutError: locator.click: Timeout 30000ms exceeded

或者：

Target page, context or browser has been closed

这类报错只能说明“某个动作失败了”，但不能说明为什么失败。

真正排查时，你还需要知道：

• 这次任务跑的是哪个 Profile
• 浏览器是不是目标实例
• 代理出口 IP 是否符合预期
• 登录态是否来自同一个会话
• 页面失败时处在哪个 URL
• 是否有多个任务抢同一个环境
• 失败前是否发生过重试、跳转、验证码或权限弹窗

如果这些信息没有记录，后面再怎么改脚本，都是半盲调试。

为什么 CSDN 上很多浏览器自动化教程到这里就断了

很多教程会教你：

• 怎么启动 Playwright
• 怎么定位元素
• 怎么截图
• 怎么等待网络请求
• 怎么处理超时

这些都对，但它们默认你操作的是一个“干净、单次、可重复”的测试页面。

真实业务环境不是这样。

真实任务里，浏览器环境可能包含：

• 固定 Profile
• Cookie
• LocalStorage
• IndexedDB
• 代理配置
• 时区和语言
• 扩展状态
• 自动化入口
• AI Agent 执行记录

这时，脚本失败不一定是代码错了，也可能是环境变了。

所以自动化排查的第一原则是：不要只记录动作日志，要记录环境日志。

先定义一个任务日志结构

可以先从最小结构开始。

{
  "task_id": "task-20260530-001",
  "profile_id": "profile-us-001",
  "browser_entry": "cdp",
  "proxy_id": "proxy-us-01",
  "egress_ip": "unknown",
  "timezone": "America/New_York",
  "language": "en-US",
  "start_url": "https://example.com/login",
  "current_url": "",
  "login_state": "unknown",
  "retry_count": 0,
  "result": "running",
  "error": null
}

这里不追求复杂，先保证每次任务能回答一个问题：这次失败发生在哪个浏览器环境里。

如果连 profile_id、proxy_id、current_url 都没有，排查就只能靠回忆。

Playwright 里怎么落地

下面是一个简化示例。

import { chromium } from 'playwright';

const taskLog = {
  task_id: `task-${Date.now()}`,
  profile_id: 'profile-us-001',
  browser_entry: 'persistent-context',
  proxy_id: 'proxy-us-01',
  egress_ip: 'unknown',
  timezone: 'America/New_York',
  language: 'en-US',
  start_url: 'https://example.com',
  current_url: '',
  login_state: 'unknown',
  retry_count: 0,
  result: 'running',
  error: null
};

function logEvent(event, extra = {}) {
  console.log(JSON.stringify({
    time: new Date().toISOString(),
    event,
    ...taskLog,
    ...extra
  }));
}

const context = await chromium.launchPersistentContext('./profiles/profile-us-001', {
  headless: false
});

const page = await context.newPage();

try {
  logEvent('task_started');

  await page.goto(taskLog.start_url, { waitUntil: 'domcontentloaded' });
  taskLog.current_url = page.url();

  logEvent('page_opened');

  await page.screenshot({ path: `screenshots/${taskLog.task_id}-start.png` });

  const title = await page.title();
  logEvent('page_checked', { title });

  taskLog.result = 'success';
  logEvent('task_finished');
} catch (error) {
  taskLog.result = 'failed';
  taskLog.error = error.message;
  taskLog.current_url = page.url();

  await page.screenshot({ path: `screenshots/${taskLog.task_id}-failed.png` });

  logEvent('task_failed');
} finally {
  await context.close();
}

这段代码不解决所有问题，但它做了一件关键的事：把任务、Profile、页面状态和失败现场绑定起来。

不要只记录 selector，要记录浏览器入口

在浏览器自动化里，入口差异很大。

常见入口包括：

• Playwright 自己 launch 新浏览器
• launchPersistentContext 启动固定用户目录
• connectOverCDP 连接已有浏览器
• 通过 MCP 或 AI Agent 间接控制浏览器
• 通过无头任务队列后台执行

这些入口看到的环境可能完全不同。

例如你以为自己在复用登录态，但代码实际启动了一个新环境：

const browser = await chromium.launch();
const context = await browser.newContext();

这适合一次性测试，不适合长期账号环境。

如果你要复用 Profile，至少要明确：

const context = await chromium.launchPersistentContext('./profiles/account-001', {
  headless: false
});

如果你是接入已有浏览器，也要记录连接方式：

const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');

这里建议把 browser_entry 写进日志，而不是只写“启动成功”。

代理日志不能只写配置值

很多人会在配置里写了代理，然后默认代理已经生效。

但排查时需要确认的是：页面真实出口 IP 是什么。

可以在任务启动后做一个独立检测：

await page.goto('https://api.ipify.org?format=json');
const ipText = await page.textContent('body');

logEvent('egress_ip_checked', {
  egress_response: ipText
});

如果不能访问第三方检测接口，也可以换成团队内部的 IP 回显服务。

关键是不要只记录：

proxy = proxy-us-01

而要记录：

proxy_id = proxy-us-01
egress_ip = 104.xx.xx.xx
profile_id = profile-us-001

这样代理异常时，才能判断是代理没生效、Profile 绑定错了，还是脚本连错了浏览器实例。

失败截图要和日志放在一起

截图不是为了好看，而是为了还原状态。

建议失败时至少保存三类文件：

logs/task-20260530-001.jsonl
screenshots/task-20260530-001-failed.png
html/task-20260530-001-failed.html

Playwright 可以这样保存页面 HTML：

const html = await page.content();
await fs.promises.writeFile(`html/${taskLog.task_id}-failed.html`, html);

这样你不会只看到一个 TimeoutError，而是能看到失败时页面到底是登录页、验证码页、空白页，还是权限弹窗。

给多账号任务加 Profile 锁

如果多个任务同时抢同一个 Profile，日志会非常混乱。

例如：

task-A 使用 profile-001 登录
task-B 同时打开 profile-001 刷新页面
task-A 写入 Cookie
task-B 触发风控
task-A 超时

从表面看，像是 Playwright 不稳定。

实际问题是 Profile 没有并发控制。

最简单的做法是给 Profile 加锁：

{
  "profile_id": "profile-001",
  "status": "running",
  "task_id": "task-20260530-001",
  "locked_at": "2026-05-30T06:30:00.000Z"
}

任务结束后释放锁。任务异常退出时，按超时时间回收锁。

这个逻辑很基础，但对 AI Agent 浏览器自动化、多账号巡检、批量页面检查都很重要。

一份可直接用的排查清单

当浏览器自动化失败时，可以按下面顺序查：

1. 这次任务的 task_id 是什么
2. 使用的是哪个 profile_id
3. 浏览器入口是 launch、persistent context，还是 CDP
4. 页面真实出口 IP 是否记录
5. 当前 URL 是否记录
6. 失败截图是否保存
7. 页面 HTML 是否保存
8. 是否出现多个任务共用同一 Profile
9. 是否发生重试
10. 登录态是否真的来自同一个 Profile

如果这些问题都没有答案，就先别急着改业务代码。

先把日志打全。

Web4 Browser 在这里适合放在哪一层

如果只是写一个本地测试脚本，普通 Playwright 足够。

但如果任务开始涉及多账号、代理、Profile、AI Agent、MCP、无头执行和团队协作，就需要把浏览器环境本身管理起来。

这也是 AI 指纹浏览器和自动化工作台 这类工具的价值：不是只开更多窗口，而是把 Profile、代理、任务、日志和异常记录放进同一套可控流程里。

Web4 Browser 的定位更接近“可自动执行的账号工作站”。对开发者来说，重点不是品牌名，而是这种架构思路：每个浏览器环境都应该有边界、有状态、有日志、有复盘依据。

如果你想继续看这类排查思路，可以参考它的 浏览器自动化与 Profile 排查文章。

最后

浏览器自动化稳定性，不是靠无限加 timeout 解决的。

脚本只是执行层，环境才是现场。

当你能把 Profile、代理、入口、页面状态、截图、HTML 和错误日志放到一起，很多“偶发失败”才会变成可以复现的问题。

能复现，就能定位。

能定位，才有资格谈优化。