SecretAgent API参考：掌握高效网页抓取的关键接口

发布时间：2026/7/19 18:37:13

SecretAgent API参考：掌握高效网页抓取的关键接口

【免费下载链接】secret-agentThe web scraper that's nearly impossible to block - now called @ulixee/hero项目地址: https://gitcode.com/gh_mirrors/se/secret-agent

想要构建一个难以被检测的网页抓取工具吗？SecretAgent正是您需要的终极解决方案！作为一款专为网页抓取设计的现代无头浏览器，SecretAgent提供了一套强大而直观的API接口，让开发者能够轻松实现高效、稳定的数据采集任务。本文将为您详细介绍SecretAgent的核心API接口，帮助您快速掌握这个强大的网页抓取工具。

🚀 什么是SecretAgent？

SecretAgent是一个基于Chrome引擎构建的网页浏览器，专门为网页抓取和数据采集任务而设计。与其他自动化测试工具不同，SecretAgent从一开始就考虑到了网页抓取的特殊需求，提供了完整的DOM API支持、浏览器指纹伪装、资源拦截等高级功能。

通过client/lib/Agent.ts和client/lib/Tab.ts等核心模块，SecretAgent实现了强大的网页交互能力。项目的主要优势包括：

完整的DOM API支持：无需复杂的回调函数和多上下文切换
浏览器指纹伪装：模拟任何现代浏览器，避免被网站检测
资源拦截控制：精确控制加载的资源类型，提高抓取效率
异步事件处理：内置完善的等待机制，确保页面完全加载

📋 核心API接口概览

Agent类：主控制入口

Agent类是SecretAgent的核心控制类，负责管理整个抓取会话的生命周期。通过Agent实例，您可以控制浏览器行为、管理标签页、处理页面交互等。

const agent = require('secret-agent'); (async () => { await agent.goto('https://example.org'); const title = await agent.document.title; await agent.close(); })();

主要属性包括：

document：当前页面的文档对象
tabs：所有打开的标签页
url：当前页面URL
sessionId：会话唯一标识符

页面导航与加载控制

SecretAgent提供了多种页面导航和等待机制，确保数据抓取的稳定性：

// 基本页面导航 await agent.goto('https://example.com'); // 等待页面完全加载 await agent.waitForPaintingStable(); // 等待特定元素出现 await agent.waitForElement('div.content', { timeoutMs: 5000 }); // 等待资源加载完成 await agent.waitForResource({ url: '/api/data.json' });

这些API定义在client/interfaces/IWaitForOptions.ts和client/interfaces/IWaitForElementOptions.ts中，提供了丰富的配置选项。

DOM操作与元素选择

SecretAgent最大的优势之一是提供了完整的DOM API，让您可以使用熟悉的Web标准方法操作页面元素：

// 获取页面标题 const title = await agent.document.title; // 查询单个元素 const element = await agent.document.querySelector('.article-content'); // 查询多个元素 const links = await agent.document.querySelectorAll('a.article-link'); // 获取元素属性 const href = await link.getAttribute('href'); const text = await link.textContent; // 操作表单元素 const input = await agent.document.querySelector('input[name="search"]'); await input.focus(); await agent.type('搜索关键词'); await agent.click('button[type="submit"]');

🔧 高级功能API

资源管理与拦截

SecretAgent允许您精确控制页面加载的资源，这对于提高抓取效率和减少带宽消耗非常重要：

// 配置资源拦截 const agent = new Agent({ blockedResourceTypes: ['Image', 'Stylesheet', 'Font'] }); // 监听资源请求 agent.on('resource', (resource) => { console.log(`资源类型: ${resource.type}, URL: ${resource.url}`); }); // 等待特定资源 const resource = await agent.waitForResource({ type: 'XHR', url: /api\/data/ });

相关接口定义在client/interfaces/IWaitForResourceFilter.ts中。

浏览器指纹伪装

为了避免被网站检测和屏蔽，SecretAgent提供了强大的浏览器指纹伪装功能：

import { HumanEmulator } from '@secret-agent/plugin-default-human-emulator'; const agent = new Agent({ userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36', viewport: { width: 1920, height: 1080 }, humanEmulator: new HumanEmulator() }); // 模拟人类操作行为 await agent.interact({ move: { x: 100, y: 200 }, click: { selector: 'button.submit' }, type: { selector: 'input.search', text: '关键词' } });

多标签页管理

SecretAgent支持同时管理多个标签页，这对于并行抓取任务非常有用：

// 创建新标签页 const newTab = await agent.newTab(); // 切换到新标签页 await newTab.goto('https://another-site.com'); // 在所有标签页中执行操作 for (const tab of agent.tabs) { console.log(`标签页URL: ${await tab.url}`); } // 关闭特定标签页 await newTab.close();

🛠️ 实用API技巧

错误处理与重试机制

在实际的网页抓取中，错误处理至关重要。SecretAgent提供了完善的错误处理机制：

try { await agent.goto('https://example.com'); await agent.waitForPaintingStable(); // 检查页面状态 const status = await agent.status; if (status !== 200) { throw new Error(`页面加载失败，状态码: ${status}`); } } catch (error) { console.error('抓取失败:', error.message); // 重试机制 if (error.message.includes('timeout')) { console.log('正在重试...'); await agent.reload(); } }

性能优化配置

通过合理的配置，可以显著提升SecretAgent的抓取性能：

const agent = new Agent({ // 连接配置 connectionTimeout: 30000, maxConcurrentConnections: 5, // 内存优化 maxHeapSize: '2g', // 缓存配置 cacheEnabled: true, cacheMaxAge: 3600000, // 请求优化 requestTimeout: 15000, maxRedirects: 5 });

数据提取与处理

SecretAgent不仅能够抓取页面，还能方便地提取和处理数据：

// 提取结构化数据 const articles = []; const articleElements = await agent.document.querySelectorAll('.article'); for (const element of articleElements) { const title = await element.querySelector('h2').textContent; const content = await element.querySelector('.content').textContent; const date = await element.querySelector('.date').textContent; articles.push({ title, content, date }); } // 保存数据 agent.output = { articles, timestamp: new Date().toISOString(), sourceUrl: await agent.url };

📊 实际应用场景

电商价格监控

const handler = new Handler({ maxConcurrency: 3 }); async function monitorPrice(agent) { const productUrl = agent.input.url; await agent.goto(productUrl); await agent.waitForElement('.product-price'); const price = await agent.document.querySelector('.product-price').textContent; const stock = await agent.document.querySelector('.stock-status').textContent; return { url: productUrl, price: parseFloat(price.replace('¥', '')), stock: stock.includes('有货'), timestamp: new Date() }; } // 监控多个产品 const products = [ 'https://example.com/product/1', 'https://example.com/product/2', 'https://example.com/product/3' ]; for (const url of products) { handler.dispatchAgent(monitorPrice, { input: { url } }); }

新闻聚合抓取

async function scrapeNews(agent) { await agent.goto('https://news.example.com'); // 等待动态内容加载 await agent.waitForResource({ type: 'XHR', url: /api\/articles/ }); const newsItems = []; const articles = await agent.document.querySelectorAll('.news-article'); for (const article of articles) { const title = await article.querySelector('h3').textContent; const summary = await article.querySelector('.summary').textContent; const link = await article.querySelector('a').getAttribute('href'); // 访问详情页获取完整内容 const detailAgent = await agent.newTab(); await detailAgent.goto(link); const fullContent = await detailAgent.document.querySelector('.article-content').textContent; await detailAgent.close(); newsItems.push({ title, summary, link, content: fullContent }); } return newsItems; }

🔍 调试与监控

SecretAgent提供了丰富的调试和监控功能，帮助您优化抓取流程：

// 启用详细日志 process.env.DEBUG = 'secret-agent:*'; // 监控性能指标 agent.on('metrics', (metrics) => { console.log('页面加载时间:', metrics.loadTime); console.log('DOM大小:', metrics.domSize); console.log('网络请求数:', metrics.requestCount); }); // 截图功能（用于调试） await agent.screenshot({ path: 'debug-screenshot.png', fullPage: true }); // 录制用户操作（用于回放分析） await agent.startRecording(); // ...执行操作... const recording = await agent.stopRecording();