sqdshguy/wreq-js
GitHub: sqdshguy/wreq-js
一个基于 Rust 原生绑定的 Node.js HTTP 客户端，通过模拟浏览器 TLS 指纹来绕过 Cloudflare 等服务的反Bot检测。
Stars: 98 | Forks: 6
# wreq-js
[](https://www.npmjs.com/package/wreq-js)
[](https://github.com/sqdshguy/wreq-js/actions/workflows/test.yml)
[](https://deepwiki.com/sqdshguy/wreq-js)
`wreq-js` 是一个 Node.js 和 TypeScript 的 HTTP 客户端，借助来自 [wreq](https://github.com/0x676e67/wreq) 的原生 Rust 绑定，帮助你绕过 Cloudflare 和 DataDome 等服务使用的 TLS 指纹检测。
如果你的请求在浏览器中可以正常工作，但在 Node.js 中因为网络指纹不正确而被拦截，这个库正是为你准备的。
你将保留 fetch 风格的 API，并获得浏览器配置文件级别的网络行为，而无需运行完整的浏览器。
1. 内置浏览器 TLS 和 HTTP 指纹配置，涵盖 Chrome、Firefox、Safari、Edge、Opera 和 OkHttp 家族
2. 原生 Rust 引擎，提供高吞吐量流量，且无浏览器进程开销
3. Fetch 风格的 API，支持 sessions、cookies、proxies 和传输控制
4. WebSocket 辅助函数和构造函数 API，支持 session cookie 和传输重用
5. TypeScript 优先的开发者体验，提供自动生成的类型定义
6. 原生支持 macOS、Linux 和 Windows 平台
常见搜索关键词：cloudflare bypass、datadome bypass、tls fingerprinting、ja3、ja4、browser impersonation、nodejs fetch、typescript http client。
## 替代方案对比
| 库 | 方案 | API | 备注 |
|---------|----------|-----|-------|
| **wreq-js** | Rust 原生绑定 ([wreq](https://github.com/0x676e67/wreq)) | Fetch 风格，TypeScript 优先 | 配置标签和网络行为来自原生层 |
| [CycleTLS](https://github.com/Danny-Dasilva/CycleTLS) | Go 子进程桥接 | 基于 Promise | 子进程模型 |
| [got-scraping](https://github.com/apify/got-scraping) | JavaScript HTTP 客户端自定义 | 基于 `got` | Header 和请求自定义 |
| [node-tls-client](https://github.com/Sahil1337/node-tls-client) | 原生共享库绑定 | 自定义 | 行为取决于上游原生层 |
| [curl-impersonate](https://github.com/lwthiker/curl-impersonate) | 基于 curl 的工具 | CLI 和绑定 | 二进制/工具工作流 |
## 文档
所有指南、概念和 API 参考均位于：
- https://wreq.sqdsh.win
（如果你正在寻找示例、sessions/cookies、proxy 使用、流式传输、WebSockets 或完整的 API 接口——全都在这里。）
快速链接：
1. 快速入门：https://wreq.sqdsh.win/quickstart
2. API 概览：https://wreq.sqdsh.win/api-reference/overview
3. Sessions：https://wreq.sqdsh.win/concepts/sessions
4. WebSockets：https://wreq.sqdsh.win/guides/websockets
5. 兼容性矩阵：https://wreq.sqdsh.win/concepts/compatibility-matrix
## 安装
```
npm install wreq-js
# 或
yarn add wreq-js
pnpm add wreq-js
bun add wreq-js
```
在 `package.json` 中当前配置的原生目标矩阵包括：
1. macOS (Intel 和 Apple Silicon)
2. Linux (x64 glibc 和 musl，arm64 glibc)
3. Windows (x64)
如果没有适用于你环境的预构建构件，安装过程可能会从源代码编译（需要 Rust 工具链）。
## 快速开始
```
import { fetch } from 'wreq-js';
const res = await fetch('https://example.com/api', {
browser: 'chrome_142',
os: 'windows',
});
console.log(await res.json());
```
默认情况下，独立的 `fetch()` 调用使用独立的临时 cookie 存储。
当你希望 cookie 在请求之间持久化时，请使用 `createSession()`。
## 使用 sessions（推荐）
对于**大多数实际工作负载**，请从一个 session 开始并在各个请求中重用它。
这为多步骤流程保留了一个 cookie 和请求上下文。
```
import { createSession } from 'wreq-js';
const session = await createSession({ browser: 'chrome_142', os: 'windows' });
try {
const a = await session.fetch('https://example.com/a');
const b = await session.fetch('https://example.com/b');
console.log(a.status, b.status);
} finally {
await session.close();
}
```
更多 session 模式：https://wreq.sqdsh.win
## WebSockets
使用辅助函数可以通过一个 `await` 获取已连接的 socket。
```
import { websocket } from 'wreq-js';
const ws = await websocket('wss://example.com/ws', {
browser: 'chrome_142',
headers: {
Authorization: 'Bearer token',
},
});
ws.onmessage = (event) => {
console.log(event.data);
};
ws.send('hello');
ws.close(1000, 'done');
```
当你需要类似浏览器的 `CONNECTING` 行为时，请使用构造函数。
```
import { WebSocket } from 'wreq-js';
const ws = new WebSocket('wss://example.com/ws', {
browser: 'chrome_142',
os: 'windows',
});
ws.onopen = () => {
void ws.send('connected');
};
```
使用 `session.websocket(...)` 以重用来自 session HTTP 调用的 cookies 和传输设置。
```
import { createSession } from 'wreq-js';
const session = await createSession({ browser: 'chrome_142' });
try {
await session.fetch('https://example.com/login', {
method: 'POST',
body: new URLSearchParams({ user: 'name', pass: 'secret' }),
});
const ws = await session.websocket('wss://example.com/ws');
ws.onmessage = (event) => {
console.log(event.data);
};
} finally {
await session.close();
}
```
## 何时使用
当你的 Node.js HTTP 或 WebSocket 流量由于 TLS 指纹识别或浏览器配置文件不匹配而被拦截时，请使用 `wreq-js`。
当你希望使用熟悉的 fetch 风格 API 来获得 Cloudflare bypass 和 DataDome bypass 风格的网络行为时，这是一个非常合适的选择。
它处理传输和指纹级别的行为，不负责处理 CAPTCHA 验证码，也不负责页面内的 JavaScript 执行。
如果你需要 DOM/JS 执行、CAPTCHA 验证码或完整的浏览器自动化，请改用 Playwright/Puppeteer。
## 常见问题
1. 为什么使用 sessions？
在多步骤流程中应使用 sessions，以便共享 cookie 和请求上下文。
2. 为什么在某些机器上安装时会从源代码编译？
如果没有匹配的预构建原生构件，npm 可能会从源代码进行构建。
3. 我可以在 session 中使用针对特定请求的代理覆盖吗？
是的，只需在特定的 `session.fetch(...)` 调用上传递 `transport` 即可。`proxy` 字段本身仍然是 session 作用域的。
## 来源
这是 [will-work-for-meal/node-wreq](https://github.com/will-work-for-meal/node-wreq)（最初命名为 `node-wreq`）的一个维护分支，包含持续的更新、兼容性修复和性能优化。
## 致谢
- [wreq](https://github.com/0x676e67/wreq) - 带有浏览器模拟功能的 Rust HTTP 客户端
- [wreq-util](https://github.com/0x676e67/wreq-util) - 上游生态系统中的相关浏览器配置文件工具
- [NAPI-RS](https://napi.rs/) - Rust ↔ Node.js 绑定
标签：Cloudflare绕过, DataDome绕过, GNU通用公共许可证, JA3, JA4, MITM代理, Node.js, Rust原生绑定, TLS指纹伪造, TypeScript, WebSocket, Web抓取, 依赖分析, 反爬虫绕过, 可视化界面, 多架构支持, 安全插件, 指纹反检测, 暗色界面, 浏览器指纹模拟, 网络安全, 自动化攻击, 请求伪装, 隐私保护