Crawlee 的 got-scraping HTTP 客户端:GotScrapingHttpClient 接入、原理与实战指南

原创2026-09-11 10:25:471,374 阅读
文章标签:网页爬虫浏览器控制

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,
        });
    }
}

几个关键实现细节值得展开:

  1. 方法校验:validateRequest 显式拒绝 CONNECT/connect 方法,抛出 The HTTP method CONNECT is not supported by the GotScrapingHttpClient.。原因很直观——got-scraping 是普通 HTTP 客户端,不承担代理隧道的职责。

  2. 请求体转换:Crawlee 传入的 Request 使用 Web 标准的 ReadableStream(request.body),而 got 接受 Node.js 的 Readable,因此通过 Readable.fromWeb(request.body) 桥接两种流模型。

  3. 重定向委托:followRedirect: redirect === 'follow' 把 options.redirect 语义映射到 got 的重定向开关。got 默认最多跟随 10 次重定向。

  4. 忽略 TLS 错误:当 ignoreTlsErrors 为真时,注入 https: { rejectUnauthorized: false },关闭证书校验——这正是 测试用例 验证的行为:设置该标志时 gotScraping 收到包含 https: { rejectUnauthorized: false } 的选项,未设置时则不包含任何 https 相关选项。

  5. 响应归一化: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() 是最可靠的接入方式,不要依赖隐式默认值。

限制与注意事项

结合源码与测试,使用时有几点需要留意:

  1. 不支持 CONNECT 方法:直接调用 fetch 传 CONNECT 会抛错,属预期行为;
  2. ignoreTlsErrors 语义:它映射为 https.rejectUnauthorized: false,仅对 HTTPS 证书校验生效;FetchHttpClient 无法禁用证书校验并会打印 warning,而 GotScrapingHttpClient 完整支持该选项(测试验证);
  3. 重定向上限:基类 sendRequest 上限 10 次重定向,超过抛 Too many redirects;
  4. Node.js 版本要求:包要求 node >= 22.0.0,部署时需确认运行时满足条件;
  5. README 与源码不一致:README 的 Browser 导入在当前源码中并不存在,按上文修正后的导入使用即可。

总结

@crawlee/got-scraping-client 用极小的代码面(单个类、几十行实现)把 got-scraping 的强反封锁能力接入 Crawlee 的标准化 HTTP 客户端体系:GotScrapingHttpClient 负责低层网络调用,BaseHttpClient.sendRequest 负责重定向、Cookie、代理与超时等爬虫级语义。接入方式仅需在爬虫构造器传入 httpClient: new GotScrapingHttpClient()。对于需要浏览器级请求头、代理轮换与低封锁率的无头抓取场景,这是一个开箱即用且可验证的高质量选择。

深入阅读:源码实现 · 基类契约 · 类型定义 · HTTP 客户端指南 · Got Scraping 指南 · 单元测试

登录后查看全文
crawlee