Playwright 浏览器自动化

直接使用 Playwright API 实现可靠浏览器自动化，无需 MCP 的复杂性。

安装

# 安装 Playwright
npm install -g playwright

# 安装浏览器（一次性操作，每个约 100MB）
npx playwright install chromium
# 可选：
npx playwright install firefox
npx playwright install webkit

# Ubuntu/Debian 系统依赖（需 root 权限）：
sudo npx playwright install-deps chromium

快速开始

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();
  
  await page.goto('https://example.com');
  await page.screenshot({ path: 'screenshot.png' });
  
  await browser.close();
})();

最佳实践

1. 使用 Locator（自动等待）

// ✅ 推荐：具备自动等待与重试机制
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Username').fill('user');
await page.getByPlaceholder('Search').fill('query');

// ❌ 不推荐：元素未就绪时可能失败
await page.click('#submit');

2. 优先使用面向用户的属性

// ✅ 推荐：对 DOM 结构变更具备弹性
await page.getByRole('heading', { name: 'Welcome' });
await page.getByText('Sign in');
await page.getByTestId('login-button');

// ❌ 不推荐：脆弱的 CSS 选择器
await page.click('.btn-primary > div:nth-child(2)');

3. 处理动态内容

// 等待网络空闲
await page.goto('https://spa-app.com', { waitUntil: 'networkidle' });

// 等待特定元素出现
await page.waitForSelector('.results-loaded');
await page.waitForFunction(() => document.querySelectorAll('.item').length > 0);

4. 使用 Context 实现隔离

// 每个 Context = 独立会话（含独立 Cookie、Storage）
const context = await browser.newContext();
const page = await context.newPage();

// 同一 Context 中可创建多个页面
const page2 = await context.newPage();

5. 网络请求拦截

// 模拟 API 响应
await page.route('**/api/users', route => {
  route.fulfill({
    status: 200,
    body: JSON.stringify({ users: [] })
  });
});

// 屏蔽资源加载
await page.route('**/*.{png,jpg,css}', route => route.abort());

常见模式

表单自动化

// 填写表单
await page.goto('https://example.com/login');
await page.getByLabel('Username').fill('myuser');
await page.getByLabel('Password').fill('mypass');
await page.getByRole('button', { name: 'Sign in' }).click();

// 等待跳转或结果
await page.waitForURL('/dashboard');
await expect(page.getByText('Welcome')).toBeVisible();

数据提取

// 提取表格数据
const rows = await page.$$eval('table tr', rows =>
  rows.map(row => ({
    name: row.querySelector('td:nth-child(1)')?.textContent,
    price: row.querySelector('td:nth-child(2)')?.textContent
  }))
);

// 使用 JavaScript 执行提取
const data = await page.evaluate(() => {
  return Array.from(document.querySelectorAll('.product')).map(p => ({
    title: p.querySelector('.title')?.textContent,
    price: p.querySelector('.price')?.textContent
  }));
});

截图与 PDF 生成

// 全页截图
await page.screenshot({ path: 'full.png', fullPage: true });

// 元素截图
await page.locator('.chart').screenshot({ path: 'chart.png' });

// 生成 PDF（仅 Chromium 支持）
await page.pdf({ 
  path: 'page.pdf', 
  format: 'A4',
  printBackground: true 
});

视频录制

const context = await browser.newContext({
  recordVideo: {
    dir: './videos/',
    size: { width: 1920, height: 1080 }
  }
});
const page = await context.newPage();

// ... 执行操作 ...

await context.close(); // 视频将自动保存

移动设备模拟

const context = await browser.newContext({
  viewport: { width: 375, height: 667 },
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0)',
  isMobile: true,
  hasTouch: true
});

身份认证

// 方法 1：HTTP Basic Auth
const context = await browser.newContext({
  httpCredentials: { username: 'user', password: 'pass' }
});

// 方法 2：Cookie
await context.addCookies([
  { name: 'session', value: 'abc123', domain: '.example.com', path: '/' }
]);

// 方法 3：LocalStorage
await page.evaluate(() => {
  localStorage.setItem('token', 'xyz');
});

// 方法 4：复用认证状态
await context.storageState({ path: 'auth.json' });
// 后续使用：await browser.newContext({ storageState: 'auth.json' });

高级功能

文件上传/下载

// 文件上传
await page.setInputFiles('input[type="file"]', '/path/to/file.pdf');

// 文件下载
const [download] = await Promise.all([
  page.waitForEvent('download'),
  page.click('a[download]')
]);
await download.saveAs('/path/to/save/' + download.suggestedFilename());

对话框处理

page.on('dialog', dialog => {
  if (dialog.type() === 'alert') dialog.accept();
  if (dialog.type() === 'confirm') dialog.accept();
  if (dialog.type() === 'prompt') dialog.accept('My answer');
});

Frame 与 Shadow DOM

// 按名称获取 Frame
const frame = page.frame('frame-name');
await frame.click('button');

// 按定位器获取 Frame
const frame = page.frameLocator('iframe').first();
await frame.getByRole('button').click();

// Shadow DOM
await page.locator('my-component').locator('button').click();

追踪（调试）

await context.tracing.start({ screenshots: true, snapshots: true });

// ... 运行测试 ...

await context.tracing.stop({ path: 'trace.zip' });
// 在 https://trace.playwright.dev 查看追踪记录

配置选项

const browser = await chromium.launch({
  headless: true,        // 无界面运行
  slowMo: 50,           // 每步延时 50ms（用于调试）
  devtools: false,      // 是否打开 DevTools
  args: ['--no-sandbox', '--disable-setuid-sandbox'] // Docker/Ubuntu 场景常用
});

const context = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
  locale: 'ru-RU',
  timezoneId: 'Europe/Moscow',
  geolocation: { latitude: 55.7558, longitude: 37.6173 },
  permissions: ['geolocation'],
  userAgent: 'Custom Agent',
  bypassCSP: true,      // 绕过内容安全策略（Content Security Policy）
});

错误处理

// 设置超时并重试
try {
  await page.getByRole('button', { name: 'Load' }).click({ timeout: 10000 });
} catch (e) {
  console.log('按钮未找到或不可点击');
}

// 检查元素是否存在
const hasButton = await page.getByRole('button').count() > 0;

// 自定义条件等待
await page.waitForFunction(() => 
  document.querySelectorAll('.loaded').length >= 10
);

Sudoers 配置

为 Playwright 浏览器安装配置 sudo 权限：

# /etc/sudoers.d/playwright
username ALL=(root) NOPASSWD: /usr/bin/npx playwright install-deps *
username ALL=(root) NOPASSWD: /usr/bin/npx playwright install *

参考资料

• Playwright 文档
• API 参考
• 最佳实践
• Locators 指南