# 剧作家本地浏览器自动化 **状态**：生产就绪 ✅ **最后更新**：2026-01-21 **依赖项**：Node.js 20+（Node.js 18 已弃用）或 Python 3.9+ **最新版本**：playwright@1.57.0、playwright-stealth@0.0.1、puppeteer-extra-plugin-stealth@2.11.2 **浏览器版本**：Chromium 143.0.7499.4 |火狐浏览器 144.0.2 |网络工具包26.0 > **⚠️ v1.57 重大变更**：Playwright 现在使用 [Chrome 进行测试]() 构建而不是 Chromium。这提供了更真实的浏览器行为，但会更改浏览器图标和标题栏。 ** ** ## 快速入门（5 分钟） ### 1\.安装剧作家 **Node.js**： npm install -D 剧作家 npx 剧作家安装 chromium **Python**： pip 安装剧作家剧作家安装 chromium **为什么这很重要：** * `playwright install` 下载浏览器二进制文件（Chromium 约为 400MB） * 仅安装所需的浏览器：`chromium`、`firefox` 或 `webkit` * 二进制文件存储在`~/.cache/ms-playwright/`中 ### 2\.基本页面抓取从“剧作家”导入{铬}； const browser =等待 chromium.launch({ headless: true }); const page = 等待 browser.newPage(); 等待 page.goto('https://example.com', { waitUntil: 'networkidle' }); const title = 等待 page.title(); const content = wait page.textContent('body'); 等待浏览器.close(); console.log({ 标题, 内容 }); **关键：** * 始终使用“await browser.close()”关闭浏览器以避免僵尸进程 * 对动态内容 (SPA) 使用 `waitUntil: 'networkidle'` * 默认超时为 30 秒 - 如果需要，可使用“timeout: 60000”进行调整 ### 3\.本地测试 # 节点.js npx tsx scrape.ts # Python 蟒蛇 scrape.py ** ** ## 为什么选择 Playwright Local 与 Cloudflare 浏览器渲染特色 |本地剧作家 | Cloudflare 浏览器渲染 ---|---|--- **IP 地址** |住宅（您的 ISP）|数据中心（易于检测） **隐形插件** |全力支持|不可用 **速率限制** |无 |每天 2,000 个请求免费套餐 **成本** |免费（您的CPU）|免费套餐后的 $5/10k 请求 **浏览器控制** |所有剧作家功能 |有限的API **并发** |您的硬件限制 |基于账户的限制 **会话持续性** |全面的cookie/存储控制|有限的会话管理 **用例** |受机器人程序保护的网站、身份验证流程 |简单抓取，无服务器 **何时使用 Cloudflare** ：无服务器环境、简单抓取、规模经济高效 **何时使用 Local** ：需要防机器人绕过、需要住宅 IP、复杂的自动化 ** ** ## 7 步隐形设置流程 > **⚠️ 2025 年现实检查**：隐形插件可以很好地对抗基本的反机器人措施，但高级检测系统（Cloudflare Bot Management、PerimeterX、DataDome）已经有了显着的发展。检测领域现在包括： > > * 行为分析（鼠标模式、滚动时间、击键动态） > * TLS 指纹识别（JA3/JA4 签名） > * Canvas 和 WebGL 指纹识别 > * HTTP/2 指纹识别 > > > **建议**： > > * 隐形插件是一个很好的起点，而不是一个完整的解决方案 > * 结合真实的用户行为模拟（使用 `steps` 选项） > * 考虑对受到严格保护的地点进行住宅代理 > * “今天有用的方法明天可能就行不通了”——定期测试 > * 对于高级场景，研究替代方案，例如“nodriver”或“unDetected-chromedriver” > ### 第 1 步：安装 Stealth 插件 (Node.js) npm 安装 playwright-extra playwright-stealth **对于傀儡师额外的兼容性**： npm 安装 puppeteer-extra puppeteer-extra-plugin-stealth ### 步骤 2：配置隐身模式 **剧作家额外**：从“playwright-extra”导入{chromium}；从“puppeteer-extra-plugin-stealth”导入隐身； chromium.use(stealth()); const 浏览器 = 等待 chromium.launch({ 无头：真实，参数：[ '--disable-blink-features=自动化控制', '--无沙箱', '--禁用-setuid-沙箱', ], }); const context = 等待 browser.newContext({ userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, 如 Gecko) Chrome/120.0.0.0 Safari/537.36', 视口：{宽度：1920，高度：1080}，区域设置：“en-US”， timezoneId: '美国/纽约', }); **要点：** * `--disable-blink-features=AutomationControlled` 删除 `navigator.webdriver` 标志 * 随机化视口大小以避免指纹识别 * 将用户代理与浏览器版本相匹配（上面的 Chrome 120 示例） ### 步骤 3：屏蔽 WebDriver 检测等待 page.addInitScript(() => { // 删除 webdriver 属性 Object.defineProperty(navigator, 'webdriver', { 得到：() => 未定义， }); // 模拟插件 Object.defineProperty(navigator, '插件', { 得到: () => [1, 2, 3, 4, 5], }); // 模拟语言 Object.defineProperty(navigator, '语言', { 获取：() => ['en-US', 'en'], }); // 一致的权限 const OriginalQuery = window.navigator.permissions.query; window.navigator.permissions.query = (参数) => ( parameters.name === '通知' ? Promise.resolve({ 状态:Notification.permission }) : 原始查询（参数））； }); ### 步骤 4：类人鼠标运动 // 模拟人类光标移动异步函数 humanClick(页面, 选择器) { const 元素 = 等待 page.locator(选择器); const box = await element.boundingBox(); 如果（框）{ // 移动到元素内的随机点 const x = box.x + box.width * Math.random(); const y = box.y + box.height * Math.random(); 等待 page.mouse.move(x, y, { 步骤: 10 }); 等待 page.mouse.click(x, y, { 延迟: 100 }); } } ### 步骤 5：轮换用户代理常量用户代理 = [ 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, 如 Gecko) Chrome/120.0.0.0 Safari/537.36', 'Mozilla/5.0（Macintosh；Intel Mac OS X 10_15_7）AppleWebKit/537.36（KHTML，如 Gecko）Chrome/120.0.0.0 Safari/537.36', 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, 如 Gecko) Chrome/120.0.0.0 Safari/537.36', ]; const randomUA = userAgents[Math.floor(Math.random() * userAgents.length)]; const context = 等待 browser.newContext({ 用户代理：随机UA， }); ### 步骤 6：Cookie 和会话持久性从“剧作家”导入{铬}；从“fs/promises”导入 fs； // 保存会话 const context = 等待 browser.newContext(); const page =等待context.newPage(); // ... 执行登录 ... const cookies =等待context.cookies(); 等待 fs.writeFile('session.json', JSON.stringify(cookies, null, 2)); 等待上下文.close(); // 恢复会话 const saveCookies = JSON.parse(await fs.readFile('session.json', 'utf-8')); const newContext = 等待 browser.newContext(); 等待 newContext.addCookies(savedCookies); ### 第 7 步：验证隐身性在以下位置测试您的设置： const page =等待context.newPage(); 等待 page.goto('https://bot.sannysoft.com/', { waitUntil: 'networkidle' }); 等待 page.screenshot({ 路径: 'stealth-test.png', fullPage: true }); **检查内容：** * `navigator.webdriver` 应该是 `undefined` （而不是 `false`） * 应该检测到 Chrome * 应该填充插件 * 页面上没有危险信号 ** ** ## 关键规则 ### 总是这样做 ✅ 对 SPA（React、Vue、Angular）使用 `waitUntil: 'networkidle'` ✅ 使用 `await browser.close()` 关闭浏览器以防止内存泄漏 ✅ 将自动化包装在 try/catch/finally 块中 ✅ 为不可靠的站点设置显式超时 ✅ 保存错误屏幕截图以进行调试 ✅ 在与元素交互之前使用 `page.waitForSelector()` ✅ 旋转用户代理以进行大量抓取✅ 首先使用 `headless: false` 进行测试，然后切换到 `headless: true` ### 永远不要这样做 ❌ 使用 `page.click()` 而不等待元素（首先 `waitForSelector`） ❌ 依靠固定的 `setTimeout()` 进行等待（使用 `waitForSelector`、`waitForLoadState`） ❌ 无速率限制的抓取（在请求之间添加延迟） ❌ 对所有请求使用相同的用户代理（轮换代理） ❌ 忽略导航错误（捕获并通过退避重试） ❌ 运行无头，无需先测试有头模式（可视化调试捕获问题） ❌ 在代码中存储凭据（使用环境变量） ** ** ## 调试方法 (v1.56+) Playwright v1.56 引入了无需设置事件侦听器即可捕获调试信息的新方法： ### 控制台消息从“@playwright/test”导入{测试，期望}； test('捕获控制台输出', async ({ page }) => { 等待 page.goto('https://example.com'); // 获取所有最近的控制台消息 const messages = page.consoleMessages(); // 按类型过滤 const error = messages.filter(m => m.type() === 'error'); const messages = messages.filter(m => m.type() === 'log'); console.log('控制台错误：', error.map(m => m.text())); }); ### 页面错误 test('检查 JavaScript 错误', async ({ page }) => { 等待 page.goto('https://example.com'); // 获取所有页面错误（未捕获的异常） const 错误 = page.pageErrors(); // 如果发生任何错误则测试失败期望(错误).toHaveLength(0); }); ### 网络请求 test('检查 API 调用', async ({ page }) => { 等待 page.goto('https://example.com'); // 获取最近所有的网络请求 const requests = page.requests(); // 过滤 API 调用 const apiCalls = requests.filter(r => r.url().includes('/api/')); console.log('API 调用：', apiCalls.length); // 检查是否有失败的请求 const failed = requests.filter(r => r.failure()); 期望（失败）。toHaveLength（0）； }); **何时使用**：调试测试失败、验证没有控制台错误、审核网络活动。 ** ** ## 高级鼠标控制（v1.57+） “steps”选项提供对鼠标移动的细粒度控制，可用于： * 在反机器人检测中显得更像人类 * 使用流畅的动画测试拖放 * 调试视觉交互 ### 按步骤点击 // 通过 10 个中间步骤移动到元素（更流畅、更人性化）等待 page.locator('button.submit').click({ 步骤: 10 }); // 快速点击（更少的步骤）等待 page.locator('button.cancel').click({ 步骤: 2 }); ### 逐步拖动 const source = page.locator('#draggable'); const target = page.locator('#dropzone'); // 平滑拖动动画（20步）等待源.dragTo(目标, { 步骤: 20 }); // 快速拖动（5步）等待源.dragTo(目标, { 步骤: 5 }); **反检测优势**：许多机器人检测系统都会寻找瞬时鼠标移动。使用“steps: 10”或更高可以模拟真实的人类小鼠行为。 ** ** ## 已知问题预防此技能可防止 **10** 已记录的问题： ### 问题#1：目标关闭错误 **错误**：`协议错误（Target.sendMessageToTarget）：目标已关闭。` **来源**： **为什么发生**：页面在操作完成之前关闭，或浏览器崩溃 **预防**：尝试{ 等待 page.goto(url, { 超时: 30000 }); } 捕获（错误）{ if (error.message.includes('目标已关闭')) { console.log('浏览器崩溃，正在重新启动...'); 等待浏览器.close(); 浏览器=等待 chromium.launch(); } } ### 问题#2：未找到元素 **错误**：`TimeoutError：等待选择器“按钮”失败：超出超时 30000ms` **来源**： **为什么发生**：元素不存在，选择器错误或页面尚未加载 **预防**： // 使用带有显式超时的 waitForSelector const 按钮 = 等待 page.waitForSelector('button.submit', { 状态：“可见”，超时：10000， }); 等待按钮.click(); // 或者使用具有自动等待功能的定位器等待 page.locator('button.submit').click(); ### 问题#3：导航超时 **错误**：`TimeoutError：page.goto：超出超时 30000 毫秒。` **来源**： **为什么会发生**：页面加载缓慢，无限加载旋转器，被防火墙阻止 **预防**：尝试{ 等待 page.goto(url, { waitUntil: 'domcontentloaded', // 比 networkidle 宽松 timeout: 60000, // 对于慢速站点增加 }); } 捕获（错误）{ if (error.name === '超时错误') { console.log('导航超时，检查页面是否加载...'); const title = 等待 page.title(); 如果（标题）{ console.log('尽管超时但页面已加载'); } } } ### 问题 #4：分离帧错误 **错误**：`错误：执行上下文被破坏，很可能是因为导航。` **来源**： **为什么会发生**：SPA 导航重新渲染了元素 **预防**： // 导航后重新查询元素异步函数 safeClick(页面, 选择器) { 等待页面.waitForSelector(选择器); 等待页面。单击（选择器）；等待 page.waitForLoadState('networkidle'); } ### 问题 #5：机器人检测 (403/Captcha) **错误**：页面返回 403 或显示验证码 **来源**： **为什么发生**：站点检测到 `navigator.webdriver`、数据中心 IP 或指纹不匹配 **预防**：使用隐身模式（上面的步骤 2-7）+ 住宅 IP ### 问题#6：文件下载未完成 **错误**：下载开始但从未完成 **来源**： **为什么会发生**：未等待下载事件，文件流未关闭 **预防**： const [下载] = 等待 Promise.all([ page.waitForEvent('下载'), page.click('a.download-link'), ]); const 路径 = 等待下载.path(); 等待 download.saveAs('./downloads/' + download.suggestedFilename()); ### 问题 #7：无限滚动无法加载更多内容 **错误**：滚动到达底部但没有加载新内容 **来源**： **为什么会发生**：滚动事件未正确触发，或滚动太快 **预防**：让先前的高度 = 0; 而（真）{ const currentHeight = wait page.evaluate(() => document.body.scrollHeight); if (当前高度 === 先前高度) { 打破； // 没有更多内容了 } 等待 page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); 等待页面.waitForTimeout(2000); // 等待新内容加载先前高度 = 当前高度； } ### 问题#8：WebSocket 连接失败 **错误**：`WebSocket 连接到“ws://...”失败` **来源**： **为什么会发生**：浏览器在限制性环境中启动时没有使用 `--no-sandbox` **预防**： const 浏览器 = 等待 chromium.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'], }); ### 问题 #9：page.pause() 在无头模式下禁用超时 **错误**：当 `page.pause()` 存在时，测试在 CI 中无限期挂起 **来源**：[GitHub Issue #38754]() **为什么会发生**：`page.pause()` 在无头模式下被忽略，但禁用测试超时，导致后续失败的断言永远挂起 **预防**： // 条件调试 - 仅在本地开发中暂停 if (!process.env.CI && !process.env.HEADLESS) { 等待页面.pause(); } // 或者使用环境变量 const shouldPause = process.env.DEBUG_MODE === 'true'; 如果（应该暂停）{ 等待页面.pause(); } **影响**：高 - 可能导致 CI 管道在断言失败时无限期挂起 ### 问题 #10：权限提示阻止 CI 中的扩展测试 **错误**：测试浏览器扩展时，测试挂在权限提示上 **来源**：[GitHub 问题 #38670]() **为什么会发生**：带有扩展的 `launchPersistentContext` 显示无法自动授予的不可解除的权限提示（剪贴板读/写、本地网络访问） **预防**： // 不要在 CI 中使用持久上下文进行扩展 // 使用常规上下文代替 const context = 等待 browser.newContext({ 权限：['剪贴板读取'，'剪贴板写入'] }); // 对于扩展，尽可能预先授予权限 const context = 等待 browser.newContext({ 权限：['通知'，'地理位置'] }); **影响**：高 - 阻止 CI/CD 环境中的自动扩展测试 ** ** ## 配置文件参考 ### playwright.config.ts（完整示例）从“@playwright/test”导入{defineConfig，设备}；导出默认的defineConfig({ testDir: './tests', 超时：30000，期望：{ 超时：5000， }, 完全并行：正确，禁止仅：!!process.env.CI，重试：process.env.CI？ 2：0，工人：process.env.CI？ 1：未定义，记者：'html', 使用：{ baseURL: 'http://localhost:3000', 跟踪：“第一次重试时”，屏幕截图：“仅在失败时”，视频：“失败时保留”， // 反检测设置 userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36', 视口：{宽度：1920，高度：1080}，区域设置：“en-US”， timezoneId: '美国/纽约', }, 项目：[ { 名称：“铬”，使用：{ ...devices['桌面 Chrome'] }, }, { 名称：'隐身'，使用：{ ...设备['桌面 Chrome'], 启动选项：{ 参数：[ '--disable-blink-features=自动化控制', '--无沙箱', ], }, }, }, ], }); **为什么要进行这些设置：** * `trace: 'on-first-retry'` \- 捕获调试失败测试的完整跟踪 * `screenshot: 'only-on-failure'` \- 节省磁盘空间 * `viewport: { width: 1920, height: 1080 }` \- 常用桌面分辨率 * `--disable-blink-features=AutomationControlled` \- 删除 webdriver 标志 ### 动态 Web 服务器配置 (v1.57+) 使用正则表达式开始测试之前等待 Web 服务器输出：从'@playwright/test'导入{defineConfig}；导出默认的defineConfig({ 网络服务器：{ 命令：'npm run dev'， // 等待服务器打印端口等待：{ stdout: '/服务器在端口上运行 (?\\d+)/' }, }, 使用：{ // 在测试中使用捕获的端口 baseURL: `http://localhost:${process.env.SERVER_PORT ?? 3000}` } }); **好处**： * 处理来自开发服务器的动态端口（Vite、Next.js 开发模式） * 无需进行 HTTP 就绪检查 * 命名捕获组成为环境变量 * 适用于仅记录就绪消息的服务 **何时使用**： * 具有随机端口的开发服务器 * 没有HTTP端点的服务 * 具有端口映射的容器化环境 ** ** ## 常见模式 ### 模式 1：经过身份验证的会话抓取从“剧作家”导入{铬}；从“fs/promises”导入 fs；异步函数 scrapeWithAuth() { const browser =等待 chromium.launch({ headless: false }); const context = 等待 browser.newContext(); const page =等待context.newPage(); // 登录等待 page.goto('https://example.com/login'); 等待 page.fill('input[name="email"]', process.env.EMAIL); 等待 page.fill('input[name="password"]', process.env.PASSWORD); 等待 page.click('button[type="submit"]'); 等待 page.waitForURL('**/dashboard', { 超时: 10000 }); // 保存会话 const cookies =等待context.cookies(); 等待 fs.writeFile('session.json', JSON.stringify(cookies)); // 导航到受保护的页面等待 page.goto('https://example.com/protected-data'); const data = wait page.locator('.data-table').textContent(); 等待浏览器.close(); 返回数据； } **何时使用**：需要登录、抓取用户特定内容的网站 ### 模式 2：具有重复数据删除功能的无限滚动异步函数 scrapeInfiniteScroll(页面, 选择器) { const items = new Set(); 让前一个计数 = 0; 让 noChangeCount = 0; while (noChangeCount < 3) { const elements = wait page.locator(selector).all(); for (元素的 const el) { const text = wait el.textContent(); 项目.添加(文本); } if (items.size === previousCount) { 没有更改计数++； } 否则{ 没有更改计数 = 0; } previousCount = items.size; 等待 page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); 等待页面.waitForTimeout(1500); } 返回 Array.from(items); } **何时使用**：Twitter 提要、产品列表、无限滚动的新闻网站 ### 模式 3：多选项卡编排异步函数 scrapeMultipleTabs(urls) { const 浏览器 = 等待 chromium.launch(); const context = 等待 browser.newContext(); const 结果 = 等待 Promise.all( urls.map(异步(url) => { const page =等待context.newPage(); 等待页面.goto(url); const title = 等待 page.title(); 等待页面.close(); 返回 { url, 标题 }; }) ）；等待浏览器.close(); 返回结果； } **何时使用**：同时抓取多个页面，比较购物 ### 模式 4：截图整页异步函数 captureFullPage(url, outputPath) { const 浏览器 = 等待 chromium.launch(); const page = 等待 browser.newPage({ 视口：{宽度：1920，高度：1080}， }); 等待 page.goto(url, { waitUntil: 'networkidle' }); 等待页面.screenshot({ 路径：输出路径，整页：真实，类型：'png'， }); 等待浏览器.close(); } **何时使用**：视觉回归测试、页面存档、文档 ### 模式 5：PDF 生成异步函数generatePDF（url，outputPath）{ const 浏览器 = 等待 chromium.launch(); const page = 等待 browser.newPage(); 等待 page.goto(url, { waitUntil: 'networkidle' }); 等待页面.pdf({ 路径：输出路径，格式：'A4'，打印背景：真，边距：{ 顶部：'1cm'，右：'1cm'，底部：'1cm'，左：'1cm'， }, }); 等待浏览器.close(); } **何时使用**：报告生成、发票归档、内容保存 ### 模式 6：带有验证的表单自动化异步函数 fillFormWithValidation(page) { // 填充字段等待 page.fill('input[name="firstName"]', 'John'); 等待 page.fill('input[name="lastName"]', 'Doe'); 等待 page.fill('input[name="email"]', 'john@example.com'); // 处理下拉列表等待 page.selectOption('select[name="country"]', '美国'); // 处理复选框等待 page.check('input[name="terms"]'); // 等待验证等待 page.waitForSelector('input[name="email"]:valid'); // 提交等待 page.click('button[type="submit"]'); // 等待成功消息等待 page.waitForSelector('.success-message', { 超时: 10000 }); } **何时使用**：帐户创建、表单测试、数据输入自动化 ### 模式 7：使用指数退避重试异步函数 retryWithBackoff(fn, maxRetries = 3) { for (让 i = 0; i < maxRetries; i++) { 尝试{ 返回等待 fn(); } 捕获（错误）{ if (i === maxRetries - 1) 抛出错误；常量延迟 = Math.pow(2, i) * 1000; // 1 秒、2 秒、4 秒 console.log(`在 ${delay}ms 后重试 ${i + 1}/${maxRetries}`); 等待新的 Promise(解决 => setTimeout(解决, 延迟)); } } } // 用法等待重试WithBackoff（异步（）=> { 等待 page.goto('https://unreliable-site.com'); }); **何时使用**：脆弱的网络、速率受限的 API、不可靠的网站 ** ** ## 使用捆绑资源 ### 模板（模板/）所有模板都是即用型 TypeScript 文件。从 `~/.claude/skills/playwright-local/templates/` 复制： * `basic-scrape.ts` \- 简单的页面抓取 * `stealth-mode.ts` \- 完全隐形配置 * `authenticated-session.ts` \- 登录 + 抓取模式 * `infinite-scroll.ts` \- 滚动直到没有新内容 * `screenshot-capture.ts` \- 整页屏幕截图 * `pdf- Generation.ts` \- PDF 导出 **用法示例：** # 复制模板 cp ~/.claude/skills/playwright-local/templates/stealth-mode.ts ./scrape.ts # 根据您的用例进行编辑 # 使用 tsx 运行 npx tsx scrape.ts ### 参考文献（参考文献/）克劳德可以在需要时加载文档： * `references/stealth-techniques.md` \- 完整的反检测指南 * `references/selector-strategies.md` \- CSS vs XPath vs 文本选择器 * `references/common-blocks.md` \- 已知的阻止模式和绕过 **当 Claude 应该加载这些**：在对机器人检测、选择器问题或特定于站点的阻止进行故障排除时 ### 脚本（脚本/） * `scripts/install-browsers.sh` \- 安装所有 Playwright 浏览器 **用途：** chmod +x ~/.claude/skills/playwright-local/scripts/install-browsers.sh 〜/.claude/skills/playwright-local/scripts/install-browsers.sh ** ** ## 高级主题 ### 剧作家 MCP 服务器 (v1.56+) Microsoft 提供了官方的 [Playwright MCP Server]() 用于 AI 代理集成： # 初始化AI代理配置 npx 剧作家 init-agents 这会生成以下配置文件： * **VS Code** \- Copilot 集成 * **Claude Desktop** \- Claude MCP 客户端 * **opencode** \- 开源人工智能编码工具 **主要特点**： * 使用可访问性树而不是屏幕截图（更快、更可靠） * LLM友好的结构化数据格式 * 与 GitHub Copilot 的编码代理集成 * 符合模型上下文协议 (MCP) **MCP 服务器设置**： # 全局安装 npm install -g @anthropic/mcp-playwright # 或者添加到 Claude 桌面配置 { “mcp服务器”：{ “剧作家”：{ “命令”：“npx”， “args”：[“@anthropic/mcp-playwright”] } } } **何时使用**：构建需要浏览器自动化的人工智能代理，将 Playwright 与 Claude 或其他法学硕士集成。 ** ** ## 使用 Speedboard 进行性能分析 (v1.57+) Playwright v1.57 在 HTML 报告器中引入了 Speedboard - 一个用于识别缓慢测试和性能瓶颈的专用选项卡。 **在配置中启用**：导出默认的defineConfig({ 记者：'html', }); **查看速度板**： npx 剧作家测试 --reporter=html npx 剧作家演出报告 **速度板显示什么**： * 所有测试按执行时间排序（最慢的在前） * 等待时间细分 * 网络请求持续时间 * 帮助识别低效的选择器和不必要的等待 **用例**： * 优化测试套件运行时间 * 查找调用过多 `waitForTimeout()` 的测试 * 识别影响测试的缓慢 API 响应 * 优先考虑最慢测试的重构工作 ** ** ### Docker 部署官方 Docker 镜像提供一致、可重现的环境： **当前图像** (v1.57.0)：来自 mcr.microsoft.com/playwright:v1.57.0-noble # 为了安全起见，创建非root用户 RUN groupadd -r pwuser && useradd -r -g pwuser pwuser 用户 pwuser 工作目录/应用程序复制 --chown=pwuser:pwuser 。。运行 npm ci CMD [“npx”，“剧作家”，“测试”] **可用标签**： * `:v1.57.0-noble` \- Ubuntu 24.04 LTS（推荐） * `:v1.57.0-jammy` \- Ubuntu 22.04 LTS **使用推荐标志运行**： docker run -it --init --ipc=主机 my-playwright-tests 旗帜|目的 ---|--- `--init` |防止僵尸进程（处理 PID=1） `--ipc=主机` |防止 Chromium 内存耗尽 `--cap-add=SYS_ADMIN` |仅适用于本地开发（启用沙箱） **Python 图像**：来自 mcr.microsoft.com/playwright/python:v1.57.0-noble **安全说明**： * 始终在容器内创建非root用户 * Root 用户禁用 Chromium 沙箱（安全风险） * 对不受信任的网站使用 seccomp 配置文件 * 固定到特定版本标签（避免 `:latest`） ** ** ### 通过 Bash 工具在 Claude 代码中运行 Playwright Claude Code 可以协调浏览器自动化： // 刮.ts 从“剧作家”导入{铬}；异步函数 scrape(url: string) { const browser =等待 chromium.launch({ headless: true }); const page = 等待 browser.newPage(); 等待页面.goto(url); const data = 等待 page.evaluate(() => { 返回{ 标题：文档.标题，标题：Array.from(document.querySelectorAll('h1, h2')) .map(el => el.textContent), }; }); 等待浏览器.close(); console.log(JSON.stringify(data, null, 2)); } 刮(process.argv[2]); **克劳德代码工作流程：** 1.使用Bash工具编写脚本：`npx tsx scrape.ts https://example.com` 2. 捕获 JSON 输出 3.解析分析结果 4. 生成摘要或下一步行动 ### 屏幕截图审核工作流程 // 屏幕截图-review.ts 从“剧作家”导入{铬}；异步函数 captureForReview(url: string) { const 浏览器 = 等待 chromium.launch(); const page = 等待 browser.newPage(); 等待页面.goto(url); 等待 page.screenshot({ 路径: '/tmp/review.png', fullPage: true }); 等待浏览器.close(); console.log('屏幕截图保存到/tmp/review.png'); } captureForReview(process.argv[2]); **克劳德·代码可以：** 1.通过Bash工具运行脚本 2.使用读取工具读取屏幕截图 3. 分析视觉布局 4. 提出改进建议 ### 并行浏览器上下文以提高速度从“剧作家”导入{铬}；异步函数 scrapeConcurrently(urls: string[]) { const 浏览器 = 等待 chromium.launch(); // 使用单独的上下文进行隔离 const 结果 = 等待 Promise.all( urls.map(异步(url) => { const context = 等待 browser.newContext(); const page =等待context.newPage(); 等待页面.goto(url); const title = 等待 page.title(); 等待上下文.close(); 返回 { url, 标题 }; }) ）；等待浏览器.close(); 返回结果； } **性能增益**：并行 10 个 URL 所需的时间与 1 个 URL 相同 ### 浏览器指纹防御异步函数 setupStealthContext(浏览器) { const context = 等待 browser.newContext({ userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36', 视口：{宽度：1920，高度：1080}，区域设置：“en-US”， timezoneId: '美国/纽约', // WebGL指纹防御屏幕：{ 宽度：1920，身高：1080， }, // 地理位置（如果需要）地理位置：{ 经度：-74.006，纬度：40.7128 }，权限：['地理位置']， }); 返回上下文； } ### 处理动态内容加载异步函数 waitForDynamicContent(页面, 选择器) { // 等待初始元素等待页面.waitForSelector(选择器); // 等待内容稳定（2s无变化）让以前的内容=''；让稳定计数 = 0; while (stableCount < 4) { 等待页面.waitForTimeout(500); const currentContent = wait page.locator(selector).textContent(); if (当前内容 === 先前内容) { 稳定计数++； } 否则{ 稳定计数 = 0; } 先前内容 = 当前内容； } 返回之前的内容； } ** ** ## 快速参考 ### 选择器策略战略|示例|何时使用 ---|---|--- **CSS** | `page.click('button.submit')` |标准 HTML 元素 **XPath** | `page.click('xpath=//button[text()="提交"]')` |复杂的 DOM 查询 **文字** | `page.click('text=提交')` |当文本是唯一的时 **数据属性** | `page.click('[data-testid="提交"]')` |测试自动化 **第 N 个孩子** | `page.click('ul > li:nth-child(2)')` |基于职位 ### 等待策略方法|使用案例 ---|--- `waitUntil：'加载'` |加载所有资源（默认） `waitUntil：'domcontentloaded'` | DOM 就绪，速度慢的网站速度更快 `waitUntil：'网络空闲'` | 500 毫秒无网络活动 (SPA) `page.waitForSelector(选择器)` |元素出现在 DOM 中 `page.waitForLoadState('networkidle')` |导航后 `page.waitForTimeout(ms)` |固定延迟（如果可能的话避免） ### 浏览器启动选项选项 |价值|目的 ---|---|--- `无头` | `真`/`假` |显示浏览器用户界面 `慢动作` | `100`（毫秒）|放慢调试速度 `参数` | `['--无沙箱']` |禁用沙箱 (Docker) `可执行路径` | `/path/to/chrome` |使用自定义浏览器 `下载路径` | `./下载` |下载位置 ### 隐形的通用启动参数参数：[ '--disable-blink-features=自动化控制', '--无沙箱', '--禁用-setuid-沙箱', '--禁用-dev-shm-使用', '--禁用加速 2d-canvas', '--无首次运行', '--无合子', '--单进程', '--禁用 GPU', ] ** ** ## 依赖关系 **必填**： * **playwright@1.57.0** \- 核心浏览器自动化库 * **Node.js 20+**（Node.js 18 已弃用）或 **Python 3.9+** \- 运行时 **可选（Node.js 隐形）**： * **playwright-extra@4.3.6** \- Playwright 的插件系统 * **puppeteer-extra-plugin-stealth@2.11.2** \- 反检测插件 **可选（Python 隐身）**： * **playwright-stealth@0.0.1** \- Python 隐形库 **Docker 镜像**： * `mcr.microsoft.com/playwright:v1.57.0-noble` \- Ubuntu 24.04，Node.js 22 LTS * `mcr.microsoft.com/playwright/python:v1.57.0-noble` \- Python 变体 ** ** ## 官方文档 * **剧作家**： * **Playwright API** ： * **隐形插件** : * **Context7 库 ID**：/microsoft/playwright ** ** ## 软件包版本（2026-01-10 验证） { “开发依赖项”：{ "剧作家": "^1.57.0", "@playwright/test": "^1.57.0", "剧作家-额外": "^4.3.6", "puppeteer-extra-plugin-stealth": "^2.11.2" } } **Python**：剧作家==1.57.0 剧作家隐形==0.0.1 ** ** ## 制作示例该技能基于生产网络抓取系统： * **每日抓取量**：10,000+ 页/天 * **成功率**：98%+（重试） * **绕过机器人检测**：在受保护的站点上成功率超过 95% * **错误** ：通过上述模式防止了所有 8 个已知问题 * **验证** : ✅ 住宅 IP、隐身模式、会话持久性测试 ** ** ## 故障排除 ### 问题：“可执行文件不存在”错误 **解决方案**： npx 剧作家安装 chromium # 或者对于所有浏览器： npx 剧作家安装 ### 问题：Docker 性能缓慢 **解决方案**：添加共享内存大小 # 在 Dockerfile 中运行 playwright install --with-deps chromium # 运行： docker run --shm-size=2gb 你的镜像 ### 问题：屏幕截图为空白 **解决方案**：等待内容加载等待 page.goto(url, { waitUntil: 'networkidle' }); 等待页面.waitForTimeout(1000); // 额外的缓冲区等待页面.screenshot({ 路径: 'output.png' }); ### 问题：“页面崩溃”错误 **解决方案**：减少并发或增加内存 const 浏览器 = 等待 chromium.launch({ args: ['--disable-dev-shm-usage'], // 使用 /tmp 而不是 /dev/shm }); ### 问题：验证码总是出现 **解决方案**： 1. 验证隐身模式是否处于活动状态（检查 bot.sannysoft.com） 2. 轮换用户代理 3.在动作之间添加随机延迟 4. 如果需要，使用住宅代理 ### 问题：Ubuntu 25.10 安装失败 **错误**：`无法找到软件包 libicu74`，`软件包“libxml2”没有安装候选者` **来源**：[GitHub 问题 #38874]() **解决方案**： # 使用 Ubuntu 24.04 Docker 镜像（官方支持） docker pull mcr.microsoft.com/playwright:v1.57.0-noble # 或者等待未来版本中的 Ubuntu 25.10 支持 # 跟踪问题：https://github.com/microsoft/playwright/issues/38874 **临时解决方法**（如果 Docker 不是一个选项）： # 手动安装兼容库 sudo apt-get 更新 sudo apt-get install libicu72 libxml2 ** ** ## 完整设置清单使用此清单来验证您的设置： *安装剧作家（`npm list playwright`或`pip show playwright`） * 下载浏览器（`npx playwright install chromium`） * 基本脚本运行成功 * 配置隐身模式（如果需要） * 会话保持有效 * 截图正确保存 * 错误处理包括重试 * 浏览器正常关闭（没有僵尸进程） * 首先使用 `headless: false` 进行测试 * 生产脚本使用 `headless: true` ** ** **有问题吗？有问题吗？** 1. 检查“references/common-blocks.md”以获取特定于站点的块 2. 在验证隐身设置 3.查看官方文档： 4. 确保安装了浏览器二进制文件：`npx playwright install chromium` ** ** **最后验证**：2026-01-21 | **技能版本**：3.1.0 | **更改**：添加了 2 个关键 CI 问题（page.pause() 超时、扩展权限提示）、v1.57 功能（Speedboard、webServer 等待配置）、Ubuntu 25.10 兼容性指南

本地剧作家

包含技能