Crawlee 代理 IP 配置指南：认证、轮换与采集失败排查

如果你要在 Crawlee 中做多地区公开数据采样，先把代理 IP 放进 Crawlee 的代理配置对象，再用少量请求验证出口 IP、地区和状态码。动态住宅代理 IP 更适合短时轮换，长期保持同一会话则要评估静态住宅代理 IP；只采集公开可访问或已获授权的数据，并遵守目标站服务条款与 robots.txt。

Crawlee 如何读取和使用代理 IP

Crawlee 会在创建请求上下文时从 ProxyConfiguration 取得代理地址，再由具体 Crawler 发出请求。因此，代码里创建了代理配置还不够，还要确认该对象已经传给当前 Crawler。使用浏览器型 Crawler 时，还应查看浏览器启动和页面请求是否沿用了同一配置。

以支持 proxyConfiguration 的 Crawlee 任务为例，先用环境变量保存认证信息，再从代理 IP 服务商提供的入口生成配置：

proxyConfiguration、轮换与会话配置

```js
import { CheerioCrawler, ProxyConfiguration } from 'crawlee';

const proxyConfiguration = new ProxyConfiguration({
proxyUrls: [process.env.PROXY_URL],
});

const crawler = new CheerioCrawler({
proxyConfiguration,
useSessionPool: true,
persistCookiesPerSession: true,
maxConcurrency: 1,
maxRequestRetries: 2,
requestHandler: async ({ request, response }) => {
console.log(request.url, response?.statusCode);
},
});

await crawler.run([
'https://example.com/public-page',
'https://api.ipify.org?format=json',
]);
```

出口检测 URL 必须由同一个 crawler.run() 发出；解析该响应的 IP，并将 Crawlee 脱敏日志与代理服务端出口记录按时间核对。浏览器单独打开检测页不能证明 Crawlee 使用了代理。

PROXY_URL 只放当前代理 IP 的协议、主机、端口和认证信息，不要把 API 密钥、Cookie 或目标站账号写进文章示例。先从 1 个 URL、1 个并发开始，再逐步扩大任务。

轮换、粘性会话和并发怎么配

• useSessionPool 管理 Crawlee 会话，persistCookiesPerSession 让同一会话的 Cookie 跨请求保留；这不等于代理服务端一定为每个请求更换出口。
• 每个请求都换 IP：适合短时、多地区公开页面采样，但结果可能不易复现。
• 粘性会话：适合需要连续请求的分页任务；会话时长越长，可用 IP 范围通常越窄。
• 静态住宅代理 IP：适合长期保持同一地区和身份的管理任务，不适合高频轮换。

记录请求数、成功数、失败重试数、流量和任务耗时，再计算“成功请求成本”。不要只比较套餐单价。

选择参数时可以按任务连续性判断：独立页面采样优先控制并发和请求轮换；分页、Cookie 或连续操作则优先保持会话。并发和重试同时调高，会放大失败请求和流量消耗，应先在小样本上调整一个参数再复测。

Crawlee 返回 407、403、429 和超时怎么排查

1. 配置未生效：只输出协议、脱敏主机、端口、会话 ID、状态码和耗时，不打印含账号密码的 PROXY_URL；再核对同一 crawler 的出口记录。
2. 407：核对协议、主机、端口、账号和密码是否填错或带有多余空格。
3. 403/429：降低并发和重试频率，检查目标站规则、分页方式和请求间隔；持续被拒绝时应缩小范围或停止任务，不要靠更换代理 IP 继续请求。
4. 超时或连接重置：先换同地区代理 IP，再检查请求超时、连接池和目标 URL。
5. 连续失败时停止扩大任务，保存 URL、状态码、响应头、并发、重试次数和测试时间。

如何验证代理 IP 已经生效

先在一个公开测试页和一个受控出口回显 URL 上运行少量请求，记录 Crawlee 版本、请求 URL、返回出口、状态码、响应耗时、并发和重试次数，再扩大任务。

建议把 request.url、状态码、重试次数、会话标识和关闭原因写入同一条脱敏日志。出口 IP 未变化说明配置可能未被读取；出口 IP 已变化但返回 403/429，则应转查请求频率、目标规则和会话行为。

代理 IP 只能改变出口 IP 和地区条件，不能替代目标站规则、公开数据范围或合规的请求频率。

官方文档

本文示例按 Crawlee JavaScript 常见的 ProxyConfiguration 结构编写。版本变化时，请先核对字段名和 Crawler 参数：

• Crawlee Proxy management：核对代理配置、轮换和会话管理。
• Crawlee CheerioCrawler：核对 Crawler 参数和请求处理方式。
• HTTP 状态码说明：区分认证、限流和服务端错误。

FAQ

Crawlee 代理 IP 适合什么任务？

适合合规的公开数据采样、多地区页面验证和小规模自动化测试。正式任务仍需遵守目标站规则。

轮换越频繁越好吗？

不是。轮换频率要和分页、会话、目标站风控力度匹配；频繁切换可能让结果不可复现。

出口 IP 已变化但仍返回 403 或 429 怎么办？

说明代理配置基本生效，下一步应检查并发、请求频率、会话、目标站规则和数据访问权限，不要只靠频繁更换代理 IP继续请求。

正式扩大任务前，先用 1 个公开 URL、1 个并发完成出口 IP、状态码和日志验证。需要多地区、短会话公开数据采样时，可进一步查看动态住宅代理 IP。