impit

Impit

当工作涉及 Apify Impit 时使用此技能：通过 TLS 和 HTTP 指纹模拟浏览器发送 HTTP 请求，而无需运行真实浏览器。

工作流程

1. 修改代码前，先检查本地 Impit 的使用情况：
   • 语言绑定：Node impit（npm）、Python impit（PyPI/conda），或来自 git 的 Rust crate。
   • 软件包／本机二进制版本和平台（Node ≥ 20；平台专属可选依赖）。
   • 客户端生命周期：共享的 Impit / AsyncClient / Impit::<Jar>，还是一次性客户端。
   • 指纹选择：通用的 chrome/firefox，还是带版本号的指纹（chrome151 是最新版本）/okhttp/ios18。
   • 会话需求：Cookie、代理、HTTP/3、重定向、默认请求头、超时。
2. 用户询问最新指纹、选项名称或语言绑定差异时，更新文档。请从 source-map.md 开始。
3. 对于 Node/TypeScript 的安装、ImpitOptions、fetch、响应和错误，请参阅 nodejs.md。
4. 对于 Python 和 Rust API、补丁依赖项和构建器模式，请参阅 python-rust.md。
5. 对于指纹、HTTP/3 与代理限制、Cookie、请求头优先级、多部分边界以及 Crawlee ImpitHttpClient，请参阅 fingerprints-ops.md。
6. 按照现有项目风格实现：
   • Node 工作的命令示例优先使用 bun / bunx。
   • 每种模拟身份复用一个客户端实例（连接池 + 可选 Cookie jar）。
   • 不要将 Impit 当作无头浏览器使用——它没有页面 JS、DOM 或自动化 API。

判断

• Impit 模拟 TLS ClientHello 和 HTTP 指纹（请求头、HTTP/2 设置、伪请求头）。普通的 fetch / axios / undici 无法通过 TLS JA3 类检查；Impit 可处理这一层。
• 当机器人检测拦截非浏览器客户端且不需要完整浏览器时，优先使用 Impit。网站需要执行 JavaScript 或交互流程时，优先使用真实浏览器（Playwright/Puppeteer）。
• 默认情况下，客户端的 Cookie 无状态；只有传入 cookieJar（JS）、cookie_jar/cookies（Python）或 with_cookie_store（Rust）后才会保存 Cookie。
• 当前文档不支持同时使用 HTTP/3 和代理——不要同时启用两者。
• 请求头优先级（不区分大小写）：单次请求的请求头 > 实例的 headers > 浏览器模拟默认值。空字符串值会移除模拟的请求头。
• 通用的 chrome / firefox 会自动选择版本；当检测会跟踪过时签名时，请使用带版本号的指纹。
• 一个 Impit 实例 = 一个共享配置、连接池和 Cookie jar 的用户代理身份。不同身份应创建不同实例。
• 响应正文只能读取一次（兼容 Fetch）。不要重复调用 text()/json()/arrayBuffer()/bytes()；两个读取操作都需要正文时，请先使用 clone()。
• 不同语言绑定的默认值不同：Node 的 timeout 以毫秒为单位，默认跟随重定向（最多 10 次）；Python 的 timeout 以秒为单位，follow_redirects 默认为 False（最多 20 次），采用 httpx 风格。
• 遵守网站服务条款、robots 规则、速率限制和适用法律。将模拟用于合法集成、符合政策的抓取和测试，不得用于未经授权的访问或滥用。

验证

优先使用仓库现有的检查。对于重要的 Impit 工作，请包含相关检查：

• 向已知端点发送冒烟请求；断言状态，并只解析一次正文。
• 启用 http3: true 时，确认协商的协议（Python 中为 response.http_version；如可用，则检查日志／请求头）。
• 代理路径：使用 HTTP/HTTPS/SOCKS 且不启用 HTTP/3；两者都配置时应安全失败。
• 配置 Cookie jar 时进行 Cookie 往返测试（第一次响应设置 Cookie，第二次请求发送 Cookie）。
• 平台安装：确认目标操作系统／架构上的本机可选依赖能够解析（Linux 上区分 glibc 与 musl）。
• 根据 ImpitOptions / RequestInit / 错误类对 Node 使用方进行类型检查。
• Crawlee：确认爬虫使用 ImpitHttpClient 运行，并采用预期的指纹选项。