qgproxy-sdk

青果代理内部中转服务的 Node.js SDK，同时支持 ESM 与 CommonJS，要求 Node.js 18 或更高版本。

生产接入应使用 0.1.1 或更高版本；该版本会校验调用参数和服务端响应、拒绝远程明文 HTTP 与重定向，并支持安全复用同一个客户端处理并发请求。

npm install qgproxy-sdk

ESM

import { QgProxyClient } from "qgproxy-sdk";

const client = new QgProxyClient({
  token: process.env.QGPROXY_TOKEN!,
  baseUrl: process.env.QGPROXY_BASE_URL!
});

const result = await client.acquire({
  count: 10,
  area: ["440100"],
  isp: 1,
  distinct: true
});

CommonJS

const { QgProxyClient } = require("qgproxy-sdk");

const client = new QgProxyClient({
  token: process.env.QGPROXY_TOKEN,
  baseUrl: process.env.QGPROXY_BASE_URL
});

构造参数：

• token：业务专属 Token，必填；
• baseUrl：代理服务地址，必填，不提供默认值；
• timeoutMs：客户端总请求超时，默认 15000ms。

acquire() 的 waitTimeoutMs 控制服务端等待青果调用许可和响应的时间；客户端 timeoutMs 应设置得略大于它。

每个进程应复用一个 QgProxyClient。每次 acquire() 使用独立的超时信号；调用失败时可通过 QgProxyError 区分 HTTP 错误，通过 QgProxyProtocolError 识别无效的成功响应。错误响应只保留非敏感错误码。

返回结果中的 server 是代理地址，username、password 是代理认证信息，proxyUrl 是已经组合好的 HTTP 代理 URL。上述字段均属于敏感信息，不要写入业务日志。

Token 由 qgproxy 管理员按业务分别创建，不要写入源码或提交到 Git。