穿云 NodeJS SDK 快速入门指南

Published2026-04-08 Updated2026-04-08

穿云 NodeJS SDK 基于 Axios 深度封装，在保留其原生请求配置的同时，针对 Cloudflare V2 接口逻辑进行了底层优化。它不仅支持 JA3/HTTP2 指纹模拟，还内置了跨域请求处理与强大的 Cookie 管理功能。

安装

使用您习惯的包管理器进行安装：

# Using npm:
$ npm install cloudbypass-sdk

# Using yarn:
$ yarn add cloudbypass-sdk

# Using pnpm:
$ pnpm add cloudbypass-sdk

开始使用

您可以根据项目环境选择导入方式：

// 使用 CommonJS 导入
const cloudbypass = require('cloudbypass-sdk');

// 使用 ES 模块导入
import cloudbypass from 'cloudbypass-sdk';

核心功能与配置

引入 SDK 后，其用法与 axios 高度一致。config 参数除支持所有原生配置外，还支持以下穿云专属参数：

cb_apikey: 您的 API 密钥（可从穿云控制台获取）。
cb_part: 开启 V2 接口模式的关键参数。根据文档建议，普通访问可设为 '0'。
cb_proxy: 代理地址，支持 http 和 socks5 协议。
cb_apihost: 定制化服务器地址（仅限私有化部署用户使用）。

环境变量支持：以上参数亦可通过系统环境变量 CB_APIKEY、CB_PROXY 和 CB_APIHOST 进行全局配置。

基础请求示例 (V2 模式)

针对部署了 Cloudflare JS 质询或 Turnstile 的网站（如 Etherscan），推荐使用以下配置：

import cloudbypass from 'cloudbypass-sdk';

// 访问受 Cloudflare 保护的页面
cloudbypass.get('https://etherscan.io/accounts/label/lido', {
    cb_apikey: '您的_API_KEY',
    cb_part: '0',              // 激活 V2 异步处理逻辑
    cb_proxy: 'http://proxy:port' // 建议配合穿云海外动态代理以获得最佳成功率
})
    .then(response => {
        // x-cb-status 可用于追踪验证状态
        console.log("状态码:", response.status, "穿云状态:", response.headers.get("x-cb-status"));
        console.log("页面内容:", response.data);
    })
    .catch(error => {
        const errorData = error.response ? error.response.data : error.message;
        console.error("请求失败:", errorData);
    });

账户与代理管理

1. 查询余额

cloudbypass.getBalance('您的_API_KEY').then(balance => {
    console.log(`当前账户剩余积分: ${balance}`);
}).catch(err => console.error(err));

2. 提取代理 IP

通过 createProxy 方法可快速构建并格式化穿云动态代理。

const proxy = cloudbypass.createProxy("username-res:password");

// 1. 提取美国地区动态住宅 IP
const usDynamic = proxy.copy().setDynamic().setRegion("US").toString();
console.log("动态代理:", usDynamic);

// 2. 批量提取 5 个时效为 10 分钟的代理
const pool = proxy.copy().setExpire(60 * 10).limit(5);
for (let p of pool) {
    console.log("批量提取:", p);
}

技术注意事项

重定向处理：SDK 会自动处理请求过程中的所有重定向跳转，您无需手动干预。请注意，每一次重定向响应均会根据计费规则消耗积分。
获取密钥：所有请求均需校验 cb_apikey。请访问穿云控制台获取您的专属密钥。

👉 查看完整 SDK 文档 | 前往代码生成器

穿云API 技术文档