playwright-controller

Browse webpages using Playwright with automatic loading wait, screenshots, and text extraction. Use playwright:fetch or playwright:screenshot commands. API: fetchWithPlaywright(url, options), fetchElementAndScreenshot(url, selector, options)

使用 Playwright 智能浏览网页，支持截图和文本提取。

核心特性

• 📱 移动端模拟: 模拟 iPhone 浏览器（375x667 分辨率）
• 🎨 移动端 User-Agent: 使用真实的移动端浏览器标识
• 🔄 有头模式: 可见浏览器窗口，支持手动操作（如点击登录）
• 📸 完整资源加载: 所有资源正常加载，包括图片、CSS、字体等
• ⏳ 智能等待: 自动等待页面完全加载
• 📝 文本提取: 自动提取页面文本内容

基本用法

fetch - 获取网页内容和截图

bash

playwright:fetch <url>

自动等待 JS/CSS 加载完成，截取全屏截图，并提取页面文本内容。

特点：

• 📱 移动端模拟（375x800 分辨率）
• 🎨 移动端 User-Agent（iPhone 17.0）
• 🔄 有头模式（可见浏览器，支持手动操作如登录）
• 📸 完整资源加载（图片、CSS、字体全部正常加载）
• ⏳ 自动等待网络空闲
• 📄 同时保存截图和文本文件

示例：

bash

playwright:fetch https://baike.baidu.com/item/兴盛优选/23451097

输出：

• 截图：./screenshots/<timestamp>_<url_hash>.png
• 文本：./screenshots/<timestamp>_<url_hash>_content.txt
• 命令执行信息输出到控制台

高级用法

自定义配置

bash

playwright:fetch --timeout=120000 --dir=/custom/path <url>

参数：

• --timeout: 超时时间（毫秒），默认 60000
• --dir: 截图和文本文件保存目录，默认 ./screenshots
• <url>: 目标网页 URL

示例：

bash

playwright:fetch --timeout=120000 --dir=/Users/chenkuan/Desktop/screenshots https://baike.baidu.com/item/兴盛优选/23451097

截取特定元素

bash

playwright:fetch-element --selector=".content" <url>

截取指定 CSS 选择器元素的截图和文本内容。

示例：

bash

playwright:fetch-element --selector="h1" https://baike.baidu.com/item/兴盛优选/23451097

输出文件结构

执行后会生成以下文件：

text

screenshots/
├── 1716982345678_www_baike_baidu_com_item_兴盛优选_23451097.png    # 全屏截图
├── 1716982345678_www_baike_baidu_com_item_兴盛优选_23451097_content.txt  # 页面文本
└── 1716982345678_www_baike_baidu_com_item_兴盛优选_23451097_element.png # 元素截图

工作流程

1. 启动浏览器 - 使用 Chromium
2. 设置拦截规则 - 跳过图片、CSS、字体等资源
3. 访问页面 - 等待网络空闲（networkidle）
4. 等待渲染 - 额外等待 2 秒确保完全渲染
5. 截取截图 - 全屏 PNG 截图
6. 提取文本 - 移除广告/脚本元素，提取文本内容
7. 保存文件 - 截图和文本文件保存到指定目录

优势特点

✅ 自动加载等待 - 无需手动等待 JS/CSS 加载 ✅ 智能资源拦截 - 跳过图片等无关资源，提高速度 ✅ 全屏截图 - 保存完整的页面视觉信息 ✅ 文本提取 - 适合后续文本处理和 AI 分析 ✅ 稳定可靠 - 使用有头模式便于调试 ✅ 错误处理 - 即使失败也会保存截图 ✅ 时间戳命名 - 避免文件名冲突

注意事项

1. 浏览器启动时间 - 首次使用需要启动浏览器，约 2-3 秒
2. 网络依赖 - 需要网络连接访问目标网页
3. 文件权限 - 确保目录有写入权限
4. 长时间任务 - 复杂网页可能需要较长时间（60-120秒）

主要 API 描述

fetchWithPlaywright(url, options)

获取整个网页的内容和截图。

参数：

• url (string, 必需): 目标网页 URL
• options (object, 可选):
  • headless (boolean): 是否无头模式，默认 false
  • timeout (number): 超时时间（毫秒），默认 60000
  • screenshotDir (string): 截图保存目录，默认 './screenshots'

返回：

javascript

{
  content: string,        // 页面文本内容
  screenshotPath: string, // 截图文件路径
  title: string,          // 页面标题
  timestamp: number       // 时间戳
}

工作流程：

1. 启动 Chromium 浏览器（有头模式）
2. 设置请求拦截（跳过图片、CSS、字体等）
3. 访问 URL，等待 networkidle（网络空闲）
4. 等待 2 秒确保完全渲染
5. 截取全屏截图（1920x1080）
6. 提取文本内容（移除广告、脚本等）
7. 保存截图和文本文件

示例：

javascript

const { fetchWithPlaywright } = require('./playwright-crawler-v3.js');

const result = await fetchWithPlaywright('https://example.com', {
  headless: false,
  timeout: 60000,
  screenshotDir: './screenshots'
});

console.log(result.content);        // 页面文本
console.log(result.screenshotPath); // 截图路径

fetchElementAndScreenshot(url, selector, options)

获取指定 CSS 选择器元素的截图和文本。

参数：

• url (string, 必需): 目标网页 URL
• selector (string, 必需): CSS 选择器（如 '.content', 'h1', '#article'）
• options (object, 可选):
  • headless (boolean): 是否无头模式，默认 false
  • timeout (number): 超时时间（毫秒），默认 60000
  • screenshotDir (string): 截图保存目录，默认 './screenshots'

返回：

javascript

{
  content: string,        // 元素文本内容
  screenshotPath: string, // 元素截图文件路径
  title: string,          // 页面标题
  timestamp: number       // 时间戳
}

示例：

javascript

const { fetchElementAndScreenshot } = require('./playwright-crawler-v3.js');

const result = await fetchElementAndScreenshot(
  'https://example.com',
  '.article-content',
  {
    headless: false,
    screenshotDir: './screenshots'
  }
);

console.log(result.content);        // 元素文本
console.log(result.screenshotPath); // 截图路径

Playwright 核心功能

1. 智能页面加载等待

• 使用 page.goto(url, { waitUntil: 'networkidle' })
• 等待网络空闲（所有网络请求完成）
• 移动端模拟和完整资源加载
• 避免页面未加载完成的截图

2. 完整资源加载

javascript

// 不设置任何拦截规则，让所有资源正常加载
// 包括：图片、CSS、字体、JavaScript 等
// 这样截图才能看到完整的页面效果

3. 移动端模拟

javascript

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

3. 截图功能

• 全屏截图：page.screenshot({ fullPage: true })
• 元素截图：element.screenshot()
• PNG 格式（无损）
• 分辨率：1920x1080

4. 文本提取

javascript

const content = await page.evaluate(() => {
  document.body.innerText;  // 获取文本内容
});

5. 元素定位

javascript

// CSS 选择器
const element = await page.$('.content');      // 单个元素
const elements = await page.$$('.article');    // 多个元素

// 使用选择器
await element.$eval('h2', el => el.innerText);  // 提取元素文本

常用配置选项

headless 模式

javascript

// 有头模式（可见浏览器，适合调试）
const browser = await chromium.launch({ headless: false });

// 无头模式（后台运行，速度更快）
const browser = await chromium.launch({ headless: true });

viewport（视口大小）- 默认移动端

javascript

const context = await browser.newContext({
  viewport: { width: 375, height: 800 }  // 375x800
});

userAgent（浏览器标识）- 默认移动端

javascript

const context = await browser.newContext({
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1'
});

isMobile（移动设备模拟）

javascript

const context = await browser.newContext({
  isMobile: true  // 开启移动设备模拟
});

输出文件

自动生成的文件：

text

screenshots/
├── 1716982345678_www_example_com_content.png        # 全屏截图
├── 1716982345678_www_example_com_content.txt        # 页面文本
├── 1716982345678_www_example_com_article.png        # 元素截图
└── 1716982345678_www_example_com_error.png         # 错误截图

文件命名规则：

• 时间戳 + URL 哈希 + 后缀
• URL 哈希：移除 https:// 并替换非字母数字字符为下划线

技术实现

基于 Node.js Playwright 库实现，提供以下功能：

• 智能页面加载等待
• 自动资源拦截
• 元素定位和截图
• 文本内容提取
• 错误处理和日志

实现文件：

• playwright-cmd.js - 命令行接口
• playwright-crawler-v3.js - 核心抓取功能

依赖

• Node.js (>=16.0.0)
• Playwright (v1.58.2+)
• Chromium 浏览器（已自动安装）

安装

Skill 已内置所有依赖，无需额外安装：

bash

# 直接使用即可
playwright:fetch https://example.com