Playwright 浏览器自动化

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

安装

bash

安装 Playwright

npm install -g playwright

安装浏览器（一次性操作，每个约 100MB）

npx playwright install chromium

可选：

npx playwright install firefox npx playwright install webkit

Ubuntu/Debian 系统依赖：

sudo npx playwright install-deps chromium

快速开始

javascript
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. 使用定位器（自动等待）

javascript
// ✅ 推荐：使用自动等待和重试
await page.getByRole(button, { name: 提交 }).click();
await page.getByLabel(用户名).fill(user);
await page.getByPlaceholder(搜索).fill(query);

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

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

javascript
// ✅ 推荐：对 DOM 变化有弹性
await page.getByRole(heading, { name: 欢迎 });
await page.getByText(登录);
await page.getByTestId(login-button);

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

3. 处理动态内容

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

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

4. 使用上下文实现隔离

javascript
// 每个上下文 = 隔离的会话（cookies、存储）
const context = await browser.newContext();
const page = await context.newPage();

// 同一上下文中的多个页面
const page2 = await context.newPage();

5. 网络拦截

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

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

常见模式

表单自动化

javascript
// 填写表单
await page.goto(https://example.com/login);
await page.getByLabel(用户名).fill(myuser);
await page.getByLabel(密码).fill(mypass);
await page.getByRole(button, { name: 登录 }).click();

// 等待导航/结果
await page.waitForURL(/dashboard);
await expect(page.getByText(欢迎)).toBeVisible();

数据提取

javascript
// 提取表格数据
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

javascript
// 全页面截图
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
});

视频录制

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

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

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

移动端模拟

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

身份验证

javascript
// 方法 1：HTTP 基本认证
const context = await browser.newContext({
httpCredentials: { username: user, password: pass }
});

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

// 方法 3：本地存储
await page.evaluate(() => {
localStorage.setItem(token, xyz);
});

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

高级功能

文件上传/下载

javascript
// 上传
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());

对话框处理

javascript
page.on(dialog, dialog => {
if (dialog.type() === alert) dialog.accept();
if (dialog.type() === confirm) dialog.accept();
if (dialog.type() === prompt) dialog.accept(我的回答);
});

框架与 Shadow DOM

javascript
// 按名称获取框架
const frame = page.frame(frame-name);
await frame.click(button);

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

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

追踪（调试）

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

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

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

配置选项

javascript
const browser = await chromium.launch({
headless: true, // 无界面运行
slowMo: 50, // 减慢 50ms（用于调试）
devtools: false, // 打开开发者工具
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: 自定义代理,
bypassCSP: true, // 绕过内容安全策略
});

错误处理

javascript
// 带超时的重试
try {
await page.getByRole(button, { name: 加载 }).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 浏览器安装：

bash

/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 参考
• 最佳实践
• 定位器指南