在 Playwright APIRequestContext 中使用 CAPTCHA 解决结果

1. 1.

   安装依赖

   使用 Node.js 22+ 并安装 playwright 包。通过 solvethree.com 上 /downloads/ 下的 solvethree 0.1.0 版本 tarball solvethree-sdk-0.1.0.tgz 安装官方 JavaScript SDK。导入时使用 @solvethree/sdk；不要假定包注册表中已有可用版本。

2. 2.

   设置环境变量

   向 Node.js 进程提供 SOLVETHREE_API_KEY、SOLVETHREE_PROXY 和 TARGET_URL。工作区 API 密钥应保留在服务端。TARGET_URL 必须是应用实际的 POST 端点，而不只是显示 CAPTCHA 的页面。使用不含路径、查询参数或片段的 HTTP 或 HTTPS 代理 URL。

3. 3.

   确认站点配置和操作

   目标主机名需要有一个已启用且可供工作区使用的配置。请在解答前通过控制台完成设置；传入主机名不会创建配置。示例使用操作 login；如果目标需要其他操作，请相应修改。请求默认使用 reCAPTCHA Enterprise v3。

运行示例前，请准备好应用所需的表单字段，并满足会话要求。示例仅发送 CAPTCHA 响应字段。如果尚未配置主机名，请参阅站点配置设置。

import { request } from 'playwright';
import { Solvethree } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const target = new URL(process.env.TARGET_URL);
const proxy = new URL(process.env.SOLVETHREE_PROXY);
const result = await client.solve({ site: target.hostname, action: 'login', proxy: process.env.SOLVETHREE_PROXY });
const proxyConfig = { server: `${proxy.protocol}//${proxy.host}`, username: decodeURIComponent(proxy.username), password: decodeURIComponent(proxy.password) };

const targetClient = await request.newContext({
  proxy: proxyConfig, timeout: 30000,
  extraHTTPHeaders: { 'User-Agent': result.solution.userAgent, 'sec-ch-ua': result.solution.secChUa },
  // storageState: 'your-application-session.json', // only if your flow needs it
});
try {
  const response = await targetClient.post(target.href, {
    form: { 'g-recaptcha-response': result.solution.token }, maxRedirects: 0,
  });
  console.log('Application HTTP status:', response.status());
  // Inspect the response and supply the application's actual fields/CSRF/session.
} finally { await targetClient.dispose(); }

client.solve() 只创建一次任务，然后持续轮询，直到任务就绪或抛出异常。示例使用同一个代理进行解答和提交。针对 Playwright，示例将代理服务器地址与凭据分开，并对用户名和密码进行解码。

请求上下文将 solution.userAgent 和 solution.secChUa 用作请求头。表单在 g-recaptcha-response 中发送的是 solution.token，而非任务 ID。请配套使用代理和返回的身份信息；不要替换为无关的浏览器请求头，也不要将令牌发送到其他目标。

在表单中补充应用的实际字段，包括所需的凭据或 CSRF 数据。如果已有应用所需的会话，请启用可选的 storageState 设置，并将其指向该会话已保存的状态。

APIRequestContext 维护自己的 Cookie 存储，因此通过同一上下文发出的请求会保留它收到的 Cookie。它不会自动与无关联的浏览器上下文共享 Cookie。如果前置会话请求和最终 POST 需要共享 Cookie，请将它们放在同一个上下文中。提交结束后，finally 块会释放该上下文。

示例会记录应用的 HTTP 状态码，但这并不能确认登录成功。将 maxRedirects 设为零后，你会看到初始响应，而不会跟随重定向。请根据应用预期的成功响应，检查响应体、响应头和 Cookie。仅凭重定向或 HTTP 200，可能无法判断操作是否成功。

任务已就绪，但应用拒绝了 POST 请求。

先检查发出的请求：令牌字段、主机名和操作、代理、返回的身份信息、必需的表单字段、CSRF 值以及会话 Cookie。

试试这样做： 再次付费解答前，请先修正缺失或不匹配的请求数据。就绪的任务会提供可用的解答，但不保证下游应用一定接受。

解答结束时任务状态为失败。

查看 errorCode 和 error；不要将每次失败都视为余额问题。

试试这样做： 停止轮询该任务，并处理报告的原因。解答失败会退款。有关错误含义，请参阅 API 错误处理。

任务创建超时或连接中断。

确认你是否已有任务 ID，或是否使用了 requestId。连接超时并不代表创建失败。

试试这样做： 如果已有任务 ID，请获取现有任务。要让创建请求可恢复，请提供 requestId，并使用完全相同的输入复用它；这样会返回现有任务。不要立即发起另一次逻辑上独立的解答。

应用请求返回 HTTP 错误。

将目标响应与 solvethree 任务结果分开检查。

试试这样做： 在将响应体当作成功载荷处理之前，请先处理非成功响应。修正应用请求或报告的服务器错误，而不是假定问题由令牌引起。