Crawlee 的 got-scraping HTTP 客户端:GotScrapingHttpClient 接入、原理与实战指南
Crawlee 的 got-scraping HTTP 客户端:GotScrapingHttpClient 接入、原理与实战指南
@crawlee/got-scraping-client 是 Crawlee 官方提供的、基于 got-scraping 库实现的 HTTP 客户端包,核心导出 GotScrapingHttpClient,实现了 Crawlee 的 BaseHttpClient 接口。本指南以该包为主体,先演示如何把它接入 CheerioCrawler,再从源码层面剖析其请求构造、代理、重定向、Cookie 与 TLS 处理机制,最后介绍它作为可替换 HTTP 客户端在 Crawlee 生态中的定位与限制。
包定位:为什么需要独立的 HTTP 客户端
Crawlee 的爬虫在"无浏览器"场景下(如 CheerioCrawler、HttpCrawler、BasicCrawler)通过 HTTP 客户端与 Web 服务器通信,而不是启动完整的浏览器。这类客户端基于外部 HTTP 库实现,如 got-scraping 或 impit;拿到页面内容后再由 Cheerio、jsdom、linkedom 等解析库提取数据。它们比浏览器爬虫快得多,但通常无法执行客户端 JavaScript。
@crawlee/got-scraping-client 包的价值在于:把 got-scraping 强大的反封锁能力(浏览器指纹、请求头生成、代理支持)封装成 Crawlee 的标准 BaseHttpClient 接口,让任何 Crawlee 爬虫都能无缝使用,同时保留 Crawlee 自身的重试、会话与存储机制。
从 包描述 可以看到,该包依赖 @crawlee/http-client(workspace 内部依赖)与 got-scraping@^4.2.1,要求 Node.js >=22.0.0,采用 ESM 模块格式("type": "module"),对外导出 ./dist/index.js。
快速开始:接入 CheerioCrawler
按照 官方 README 示例,接入方式极其简单——把 GotScrapingHttpClient 实例传给爬虫构造器的 httpClient 选项即可:
import { CheerioCrawler, Dictionary } from '@crawlee/cheerio';
import { GotScrapingHttpClient } from '@crawlee/got-scraping-client';
const crawler = new CheerioCrawler({
httpClient: new GotScrapingHttpClient(),
async requestHandler({ $, request }) {
// Extract the title of the page.
const title = $('title').text();
console.log(`Title of the page ${request.url}: ${title}`);
},
});
crawler.run([
'http://www.example.com/page-1',
'http://www.example.com/page-2',
]);
httpClient 选项定义在 BasicCrawler 的构造参数 中(类型为 BaseHttpClient),因此所有继承自 BasicCrawler 的爬虫(CheerioCrawler、HttpCrawler 等)都支持该选项。
注意:README 示例中出现了
import { GotScrapingHttpClient, Browser } from '@crawlee/got-scraping-client'的写法。但从当前仓库源码 src/index.ts 看,该包仅导出了GotScrapingHttpClient类,并未导出Browser。实际使用请只导入GotScrapingHttpClient,否则会因导入不存在的符号而报错。
源码剖析:GotScrapingHttpClient 如何构造请求
packages/got-scraping-client/src/index.ts 是包的完整实现,全部代码仅几十行,核心是继承 BaseHttpClient 并覆写 fetch 方法:
export class GotScrapingHttpClient extends BaseHttpClient {
// 类型守卫:拒绝 CONNECT 方法
private validateRequest(request: Request): request is Request & {
method: Exclude<Request['method'], 'CONNECT' | 'connect'>;
} {
return !['CONNECT', 'connect'].includes(request.method!);
}
// 展开请求头:跳过伪头(: 开头)与 undefined 值,数组值逐项产出
private *iterateHeaders(headers: Record<string, string | string[] | undefined>): Generator<[string, string]> {
for (const [key, value] of Object.entries(headers)) {
if (key.startsWith(':') || value === undefined) continue;
if (Array.isArray(value)) {
for (const v of value) yield [key, v];
} else {
yield [key, value];
}
}
}
private parseHeaders(headers: Record<string, string | string[] | undefined>): Headers {
return new Headers([...this.iterateHeaders(headers)]);
}
override async fetch(request: Request, options?: RequestInit & CustomFetchOptions): Promise<Response> {
const { proxyUrl, redirect, ignoreTlsErrors } = options ?? {};
if (!this.validateRequest(request)) {
throw new Error(`The HTTP method CONNECT is not supported by the GotScrapingHttpClient.`);
}
const gotResult = await gotScraping({
url: request.url!,
method: request.method as Options['method'],
headers: Object.fromEntries(request.headers.entries()),
body: request.body ? Readable.fromWeb(request.body as any) : undefined,
proxyUrl,
signal: options?.signal ?? undefined,
followRedirect: redirect === 'follow',
...(ignoreTlsErrors ? { https: { rejectUnauthorized: false } } : {}),
});
const responseHeaders = this.parseHeaders(gotResult.headers);
return new ResponseWithUrl(new Uint8Array(gotResult.rawBody), {
headers: responseHeaders,
status: gotResult.statusCode,
statusText: gotResult.statusMessage ?? '',
url: gotResult.url,
});
}
}
几个关键实现细节值得展开:
-
方法校验:
validateRequest显式拒绝CONNECT/connect方法,抛出The HTTP method CONNECT is not supported by the GotScrapingHttpClient.。原因很直观——got-scraping是普通 HTTP 客户端,不承担代理隧道的职责。 -
请求体转换:Crawlee 传入的
Request使用 Web 标准的ReadableStream(request.body),而got接受 Node.js 的Readable,因此通过Readable.fromWeb(request.body)桥接两种流模型。 -
重定向委托:
followRedirect: redirect === 'follow'把options.redirect语义映射到got的重定向开关。got默认最多跟随 10 次重定向。 -
忽略 TLS 错误:当
ignoreTlsErrors为真时,注入https: { rejectUnauthorized: false },关闭证书校验——这正是 测试用例 验证的行为:设置该标志时gotScraping收到包含https: { rejectUnauthorized: false }的选项,未设置时则不包含任何https相关选项。 -
响应归一化:
got返回的是自身响应对象(rawBody、statusCode、statusMessage、headers),这里统一包装为ResponseWithUrl——它是 response.ts 中定义的Response子类,额外携带原始请求的url字段,并处理了 101/204/205/304 等无响应体状态码。
BaseHttpClient 契约:sendRequest 层的重定向、Cookie 与代理管理
GotScrapingHttpClient 只实现了低层 fetch,而真正的"爬虫友好"行为在基类 base-http-client.ts 的 sendRequest 中完成。理解这层分工,才能明白客户端在爬虫里的实际调用链:
async sendRequest(initialRequest: Request, options?: SendRequestOptions): Promise<Response> {
const maxRedirects = 10;
let currentRequest = initialRequest;
let redirectCount = 0;
const { proxyUrl, cookieJar, signal, fingerprint, ignoreTlsErrors } = await this.resolveRequestContext(options);
currentRequest = initialRequest.clone();
while (true) {
await this.applyCookies(currentRequest, cookieJar);
const response = await this.fetch(currentRequest, {
signal, proxyUrl, cookieJar, fingerprint, ignoreTlsErrors, redirect: 'manual',
});
await this.setCookies(response, cookieJar);
if (this.isRedirect(response)) {
if (redirectCount++ >= maxRedirects) {
throw new Error(`Too many redirects (${maxRedirects}) while requesting ${currentRequest.url}`);
}
currentRequest = this.buildRedirectRequest(currentRequest, response, initialRequest);
continue;
}
return response;
}
}
要点:
- 手动跟随重定向:基类以
redirect: 'manual'调用fetch,自己按状态码处理——303一律转为 GET 并丢弃 body;301/302在方法为 POST 时同样转为 GET;其余情况保留原方法与 body(符合 Fetch 规范)。超过 10 次重定向抛出Too many redirects错误。 - 代理解析:
resolveRequestContext中proxyUrl的优先级是options.proxyUrl显式覆盖值 →session.proxyInfo.url。也就是说,会话(Session)关联的代理会自动生效,无需手工传参。 - Cookie 合并:请求头中已有的 Cookie 与
cookieJar中的 Cookie 会合并(先克隆 jar 以免把仅存在于请求头的 Cookie 持久化进会话),响应中的Set-Cookie会被写回 jar——会话级 Cookie 管理由此闭环。 - 超时与取消:
createAbortSignal用AbortSignal.any组合外部signal与AbortSignal.timeout(timeoutMillis),任一触发都会中止请求。
CustomFetchOptions(定义位置)共包含 proxyUrl、cookieJar、fingerprint、ignoreTlsErrors 四个字段;其中 fingerprint 来自会话指纹(SendRequestOptions.session.fingerprint),ignoreTlsErrors 除显式传入外,还会在会话使用 MITM 代理(session.proxyInfo.ignoreTlsErrors)时自动开启。完整的请求选项类型见 packages/types/src/http-client.ts。
请求级选项速查
在爬虫内使用 sendRequest 上下文助手时(见 send-request.ts 的 createSendRequest),可传 SendRequestOptions 细粒度控制单次请求:
| 选项 | 类型 | 作用 |
|---|---|---|
proxyUrl |
string |
显式覆盖本次请求的代理(protocol://username:password@hostname:port 格式,如 http://auto:password@proxy.apify.com:8000);手工设置可能干扰会话代理轮换 |
timeoutMillis |
number |
请求超时(毫秒),底层转为 AbortSignal.timeout |
signal |
AbortSignal |
外部取消信号,可与超时信号组合 |
cookieJar |
CookieJar |
覆盖默认的会话 Cookie jar |
ignoreTlsErrors |
boolean |
为真时关闭 TLS 证书校验(对应 https.rejectUnauthorized: false);对使用 MITM 代理的会话自动生效 |
session |
ISession |
关联会话,提供 proxyInfo、cookieJar、fingerprint 等来源 |
关于 got-scraping 自身的丰富选项(url、method、body、headers、sessionToken、responseType、retry.limit、useHeaderGenerator、headerGeneratorOptions 等),可参考 docs/guides/got_scraping.mdx。其中与稳定性最相关的一条是:retry.limit 默认应为 0,因为 Crawlee 已有自己完善的重试管理,文档明确建议不要改动该值;useHeaderGenerator 默认为 true,用于生成浏览器风格请求头,建议保持开启。
反封锁能力:got-scraping 的核心价值
选用 got-scraping 作为底层库的最大理由是其浏览器模仿能力:got-scraping 是 Got 的扩展,能够生成接近真实浏览器的请求头与 TLS 指纹,从而显著降低被目标站点封锁的概率。具体机制包括:
- 自动生成请求头:默认启用
useHeaderGenerator: true,基于headerGeneratorOptions(可配置devices、locales、operatingSystems、browsers等维度)生成指纹; - 会话化指纹:
sessionToken作为非原始类型对象充当指纹缓存键,相同 token 的请求指纹不变,从而在使用同一会话时保持user-agent等头部一致; - 代理透传:
proxyUrl直接传递给got-scraping,配合 Crawlee 的 代理管理指南 可实现 IP 轮换。
更系统的反封锁策略可参阅 avoid_blocking.mdx。
在 Crawlee HTTP 客户端生态中的位置
HTTP 客户端指南 给出了完整的类继承关系:BaseHttpClient(抽象基类)派生出 GotScrapingHttpClient 与 ImpitHttpClient 两个具体实现。该指南说明:
- 默认客户端:文档声明
GotScrapingHttpClient是默认 HTTP 客户端,随基础 Crawlee 安装附带、无需额外安装(而ImpitHttpClient需要单独安装@crawlee/impit-client); - 切换方式:在爬虫构造器中通过
httpClient选项注入即可,可运行示例见 cheerio-got-scraping-example.ts 与 cheerio-impit-example.ts; - 职责划分:HTTP 客户端负责发送请求与接收响应、管理 Cookie 与会话、处理请求头与认证、管理代理配置、连接池与超时管理。
需要说明的是,从当前仓库源码看,BasicCrawler 的默认实现(LazyDefaultHttpClient)会优先动态加载 @crawlee/impit-client 的 ImpitHttpClient,失败时回退到原生 fetch 的 FetchHttpClient(fetch-http-client.ts,不支持代理)。因此如果你需要稳定的 got-scraping 反封锁能力,显式传入 new GotScrapingHttpClient() 是最可靠的接入方式,不要依赖隐式默认值。
限制与注意事项
结合源码与测试,使用时有几点需要留意:
- 不支持 CONNECT 方法:直接调用
fetch传 CONNECT 会抛错,属预期行为; ignoreTlsErrors语义:它映射为https.rejectUnauthorized: false,仅对 HTTPS 证书校验生效;FetchHttpClient无法禁用证书校验并会打印 warning,而GotScrapingHttpClient完整支持该选项(测试验证);- 重定向上限:基类
sendRequest上限 10 次重定向,超过抛Too many redirects; - Node.js 版本要求:包要求
node >= 22.0.0,部署时需确认运行时满足条件; - README 与源码不一致:README 的
Browser导入在当前源码中并不存在,按上文修正后的导入使用即可。
总结
@crawlee/got-scraping-client 用极小的代码面(单个类、几十行实现)把 got-scraping 的强反封锁能力接入 Crawlee 的标准化 HTTP 客户端体系:GotScrapingHttpClient 负责低层网络调用,BaseHttpClient.sendRequest 负责重定向、Cookie、代理与超时等爬虫级语义。接入方式仅需在爬虫构造器传入 httpClient: new GotScrapingHttpClient()。对于需要浏览器级请求头、代理轮换与低封锁率的无头抓取场景,这是一个开箱即用且可验证的高质量选择。
深入阅读:源码实现 · 基类契约 · 类型定义 · HTTP 客户端指南 · Got Scraping 指南 · 单元测试