playwright-local

用途

Playwright Local 用于在本地机器上构建浏览器自动化与网页抓取。相比云端方案（如 Cloudflare Browser Rendering），它使用本地住宅 IP、支持完整的隐身插件、无速率限制、可完全控制浏览器会话与 Cookie，适合需要绕过反爬、处理认证流程或复杂自动化的场景。

主要能力

支持 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、Firefox 144.0.2、WebKit 26.0。
v1.57 破坏性变更：Playwright 改用 Chrome for Testing 构建而非 Chromium，浏览器图标和标题栏会变化。
提供 7 步隐身配置流程：安装隐身插件、配置隐身模式、屏蔽 WebDriver 检测、模拟人类鼠标移动、轮换 User Agent、Cookie 与会话持久化、验证隐身效果。
提供调试方法（v1.56+）：捕获控制台消息、页面错误、网络请求。
提供高级鼠标控制（v1.57+）：通过 steps 选项实现更拟人化的点击与拖拽。
预防 10 个已知问题，包括目标关闭错误、元素未找到、导航超时、分离帧错误、机器人检测、文件下载未完成、无限滚动不加载、WebSocket 连接失败、page.pause() 在无头模式禁用超时导致 CI 挂起、扩展测试权限提示阻塞 CI。

使用方式

安装：

Node.js：

npm install -D playwright
npx playwright install chromium

Python：

pip install playwright
playwright install chromium

基础抓取示例：

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();

await page.goto('https://example.com', { waitUntil: 'networkidle' });
const title = await page.title();
const content = await page.textContent('body');

await browser.close();
console.log({ title, content });

本地测试：

# Node.js
npx tsx scrape.ts

# Python
python scrape.py

隐身配置（Node.js）：

npm install playwright-extra playwright-stealth

import { chromium } from 'playwright-extra';
import stealth from 'puppeteer-extra-plugin-stealth';

chromium.use(stealth());

const browser = await chromium.launch({
  headless: true,
  args: [
    '--disable-blink-features=AutomationControlled',
    '--no-sandbox',
    '--disable-setuid-sandbox',
  ],
});

const context = await browser.newContext({
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US',
  timezoneId: 'America/New_York',
});

适用场景

需要住宅 IP 的反爬绕过。
需要完整浏览器控制的复杂自动化。
认证流程与 Cookie/会话持久化。
浏览器扩展测试。
本地调试与测试失败排查。

限制

隐身插件对基础反爬有效，但高级检测系统（Cloudflare Bot Management、PerimeterX、DataDome）已显著进化，检测手段包括行为分析、TLS 指纹（JA3/JA4）、Canvas/WebGL 指纹、HTTP/2 指纹。
隐身插件只是起点，需结合真实用户行为模拟，重保护站点可考虑住宅代理。
“今天有效的方法明天可能失效”，需定期测试。
高级场景可研究 nodriver 或 undetected-chromedriver 等替代方案。
云端方案（Cloudflare Browser Rendering）适合无服务器环境、简单抓取和大规模成本优化场景。

关键规则

应做：SPA 使用 waitUntil: 'networkidle'；用 await browser.close() 关闭浏览器；用 try/catch/finally 包裹；设置显式超时；出错时保存截图；交互前用 page.waitForSelector()；高流量抓取轮换 User Agent；先用 headless: false 测试再切换无头模式。

不应做：未等待元素就 page.click()；依赖固定 setTimeout()；无限速抓取；所有请求用同一 User Agent；忽略导航错误；未测试有头模式就运行无头模式；在代码中存储凭据。

配置参考

playwright.config.ts 示例包含 testDir、timeout、expect、fullyParallel、forbidOnly、retries、workers、reporter，以及 use 中的 baseURL、trace、screenshot、video、userAgent、viewport、locale、timezoneId 等设置。