Visitor Tools - Tools

类型: Tools (通用工具库) 用途: 面向 Apify/Crawlee Actor 开发者的实用工具库。

一个面向 Apify/Crawlee Actor 开发者的实用工具库，提供实时截图展示（Live View）、健壮的步骤执行封装、以及常用的 Playwright 优化工具。

📦 安装

npm install @skrillex1224/visitor-tools

✨ 功能特性

1. Live View (实时截图展示)

启动一个本地 Express 服务器，在 Apify 平台的 "Live View" 选项卡中实时查看浏览器当前状态。

import { useLiveView } from '@skrillex1224/visitor-tools';

const liveView = useLiveView();

// 启动 Live View 服务器
await liveView.startLiveViewServer();

// 在循环或步骤中捕获截图
await liveView.takeLiveScreenshot(page, "正在处理步骤 1...");

工作原理：

• 截图保存到 Apify Key-Value Store
• Express 服务器从 Store 读取最新截图
• 页面每 1 秒自动刷新，展示实时状态

2. 健壮的步骤执行 (runStep)

将你的逻辑包装在 runStep 中，自动处理日志记录和失败截图。如果步骤失败，会自动捕获全页截图并将错误详情推送到 Dataset。

import { Utils } from '@skrillex1224/visitor-tools';

await Utils.runStep('登录步骤', page, async () => {
    await page.click('#login');
    await page.fill('#username', 'user');
});

失败输出示例：

{
  "status": "FAILED",
  "failedStep": "登录步骤",
  "errorMessage": "Timeout 30000ms exceeded",
  "errorStack": "...",
  "screenshotBase64": "data:image/jpeg;base64,...",
  "timestamp": "2025-12-15T03:00:00.000Z"
}

3. Playwright 优化工具

资源拦截 - 加速页面加载

通过屏蔽字体、图片、媒体等资源来加快爬取速度：

// 默认屏蔽 font, image, media
await Utils.setupBlockingResources(page);

// 自定义屏蔽类型
await Utils.setupBlockingResources(page, ['stylesheet', 'font', 'image']);

视口设置

await Utils.setupViewport(page, 1920, 1080);

4. SSE 解析工具

解析 Server-Sent Events (SSE) 流式数据的辅助函数：

const events = Utils.parseSseStream(responseText);
// 返回一个数组，包含所有解析后的 JSON 对象

5. 失败键包装 (Failed Key Wrapping)

为步骤名称添加自定义的失败标识符，方便在失败时进行分类和追踪：

import { wrapStepNameWithFailedKey, unwrapStepName, ErrorKeygen } from '@skrillex1224/visitor-tools';

// 包装步骤名称
const wrappedName = wrapStepNameWithFailedKey(ErrorKeygen.NotLogin, '等待登录');

// 解包
const [failedKey, stepName] = unwrapStepName(wrappedName);
// failedKey: 30000001
// stepName: '等待登录'

📚 完整示例

import { Actor } from 'apify';
import { PlaywrightCrawler } from 'crawlee';
import { useLiveView, Utils } from '@skrillex1224/visitor-tools';

await Actor.init();

const { startLiveViewServer, takeLiveScreenshot } = useLiveView();

const crawler = new PlaywrightCrawler({
    preNavigationHooks: [
        async ({ page }) => {
            await Utils.setupViewport(page);
            await Utils.setupBlockingResources(page);
        },
    ],
    requestHandler: async ({ page }) => {
        await takeLiveScreenshot(page, '页面加载完成');
        
        await Utils.runStep('点击登录按钮', page, async () => {
            await page.click('#login-btn');
        });
        
        await takeLiveScreenshot(page, '登录成功');
    },
});

await startLiveViewServer();
await crawler.run(['https://example.com']);
await Actor.exit();

🛠️ API 文档

useLiveView(liveViewKey?)

创建 Live View 实例。

• 参数：
  • liveViewKey (可选): Key-Value Store 中的键名，默认为 'LIVE_VIEW_SCREENSHOT'
• 返回对象：
  • startLiveViewServer(): 启动 Express 服务器
  • takeLiveScreenshot(page, logMessage?): 捕获截图并保存

Utils.runStep(stepName, page, actionFn)

执行一个步骤并自动处理失败。

• 参数：
  • stepName: 步骤名称 (支持使用 wrapStepNameWithFailedKey 包装)
  • page: Playwright Page 对象
  • actionFn: 要执行的异步函数

Utils.setupBlockingResources(page, resourceTypes?)

设置资源拦截器。

• 参数：
  • page: Playwright Page 对象
  • resourceTypes (可选): 要屏蔽的资源类型数组，默认为 ['font', 'image', 'media']

Utils.setupViewport(page, width?, height?)

设置浏览器视口大小。

• 参数：
  • page: Playwright Page 对象
  • width (可选): 宽度，默认 1920
  • height (可选): 高度，默认 1080

Utils.parseSseStream(sseStreamText)

解析 SSE 流文本为 JSON 对象数组。

• 参数：
  • sseStreamText: SSE 格式的文本
• 返回: JSON 对象数组

📝 注意事项

• Live View 仅在 Apify 平台运行时可见（通过 Live View 选项卡）
• runStep 捕获的截图是全页截图（JPEG 格式，质量 60），用于减少数据量
• 资源拦截会显著提升加载速度，但可能影响需要图片/样式的页面

📄 License

ISC