cloudscraper.js

# CloudScraper.js [](https://github.com/maarkN/cloudscraper.js/actions/workflows/ci.yml)   一个用于基于Python的CloudFlare绕过功能的Node.js封装库。该库是流行的`cloudscraper` Python库的JavaScript移植版，旨在帮助开发者在Node.js应用程序中绕过CloudFlare保护机制。 ## 🎯 目的 CloudScraper.js提供了一种无缝的方式，对CloudFlare保护的网站进行HTTP请求，自动处理JavaScript挑战、CAPTCHAs和其他保护机制。它特别适用于： - 网络爬虫应用 - 与CloudFlare保护端点集成的API - 受保护网站的自动化测试 - 从具有反机器人保护的站点收集数据 ## 🚀 功能 - **自动CloudFlare绕过**：处理JavaScript挑战和CAPTCHAs - **多平台支持**：在macOS、Linux和Windows上运行 - **安全、显式设置**：在`npm install`时不运行特权或自动脚本 - **可选安装助手**：`npm run install-deps`在需要时设置Python + 虚拟环境 - **TypeScript支持**：包含完整的类型定义 - **多个HTTP方法**：支持GET、POST、COOKIE和TOKENS ## 📦 安装 该库需要 **Node.js** 和 **Python 3** （带有 `cloudscraper` 包）。 ### 快速入门 ```bash npm install cloudscraper.js # 安装Python端（可选 — 在`npm install`时不会运行任何特权代码）： pip install cloudscraper # 或：pip install --break-system-packages cloudscraper ``` > **为什么选择可选？** 早期版本在`postinstall`时自动安装Python（包括`sudo` / Homebrew / `curl | bash`）。为了安全起见，系统包的安装现在是一个明确的选择，这使得该包可以在CI、Docker和锁定的环境中使用。 > 如果您希望使用引导助手（检测Python、创建虚拟环境、安装`cloudscraper`），请运行： > > ```bash > npm run install-deps > ``` 如果在运行时缺少`cloudscraper` Python包，则库会快速失败，并显示清晰的消息，告诉您如何安装它。请参阅 [INSTALLATION.md](./INSTALLATION.md) 获取详细信息。 ## 🔧 使用 ```javascript // ES6 import CloudScraper from "cloudscraper.js"; // CommonJS const CloudScraper = require("cloudscraper.js").default; const scraper = new CloudScraper({ usePython3: true, // 如果使用python3，则设置为true；false则使用python timeoutInSeconds: 10, }); // 简单的GET请求 scraper .get("https://example.com") .then((response) => { console.log("状态：", response.status); console.log("数据：", response.text()); }) .catch((error) => { console.error("错误：", error); }); // 带有数据的POST请求 scraper .post("https://api.example.com", { headers: { "Content-Type": "application/json" }, body: JSON.stringify({ key: "value" }), }) .then((response) => { console.log(response.json()); }); ``` ### 更快：可重用的热会话（v0.2，实验性） `createScraper()` 与一个长期运行的守护进程通信，该守护进程保持已解决的Cloudflare会话 **热**，因此重复请求会跳过重新解决挑战： ```ts import { createScraper } from "cloudscraper.js"; const scraper = await createScraper({ retries: 3, rateLimitPerHost: 1 }); const first = await scraper.get("https://www.irishjobs.ie/"); // 解决一次 const again = await scraper.get("https://www.irishjobs.ie/jobs"); // 重用会话（快速） console.log(first.status, again.status); await scraper.close(); ``` 支持 `get/post/put/delete/patch/head/cookies/tokens`，以及 `proxy`、`retries`、`rateLimitPerHost` 和 `timeoutMs`。需要Python 3 + `pip install cloudscraper`。 此API在v0.2中新增且正在演进。 ## 🤖 从AI代理使用（v0.2） LLM代理读取受反机器人保护的页面的三种方式，默认返回干净的 **markdown**。 **MCP服务器** — 将任何MCP客户端（Claude Desktop，IDE）指向 `cloudscraper-mcp` 二进制文件： ```json { "mcpServers": { "cloudscraper": { "command": "npx", "args": ["-y", "-p", "cloudscraper.js", "cloudscraper-mcp"] } } } ``` 工具：`fetch_protected_url`、`get_cookies`、`solve_challenge`。 **LangChain / LangGraph** （可选对等方`@langchain/core`）： ```ts import { createScraper, createCloudScraperTool } from "cloudscraper.js"; const tool = await createCloudScraperTool(await createScraper({ format: "markdown" })); // 将 `tool` 绑定到您的代理/图 ``` **函数调用** （OpenAI / Anthropic）— 将 `functionSchemas` 交给模型，运行处理程序： ```ts import { createScraper, fetchProtectedUrl, functionSchemas } from "cloudscraper.js"; const scraper = await createScraper(); const { text } = await fetchProtectedUrl(scraper, { url, format: "markdown" }); ``` > MCP服务器动态加载ESM MCP SDK，因此它需要 **Node ≥ 22.12** 加上Python 3 + `pip install cloudscraper`。请参阅 [`examples/`](./examples/)。 ## 🏗️ 架构 目前，SDK为每个请求生成一个短期的Python进程（运行`cloudscraper`库），并通过stdout读取结果： ```mermaid flowchart LR App[Node 应用] -->|新建 CloudScraper| SDK[cloudscraper.js] SDK -->|为每个请求生成python| Py[(python + cloudscraper)] Py -->|stdout| SDK SDK --> App ``` **v0.2（进行中）** 用一个 **长期守护进程** 替换每个请求的生成，该守护进程保持已解决的会话热（对重复调用的大幅度加速），一个强大的NDJSON IPC协议，和一流的 **AI代理接口** （一个MCP服务器 + 一个LangChain工具）： ```mermaid flowchart TB Agent[LLM 代理] -->|MCP| MCP[MCP 服务器] Dev[开发SDK] -->|createScraper| SDK[cloudscraper.js SDK] MCP --> SDK SDK <-->|NDJSON 通过套接字| D[Python 守护进程：热会话池] D -->|干净的 HTML / Markdown| SDK ``` ## 🛠️ 开发状态 **⚠️ 早期开发阶段** 该库目前处于早期开发阶段。虽然功能齐全，但它可能存在限制和重大变化，因为我们继续改进它。我们正在积极开发： - 增强的错误处理 - 更好的性能优化 - 额外的HTTP方法支持 - 改进的文档 - 更强大的CloudFlare挑战处理 **我们计划发布定期更新** 以改进功能并与最新的CloudFlare保护机制保持兼容。 ## 📚 文档 - [安装指南](./INSTALLATION.md) - 详细的设置说明 - [API参考](./docs/API.md) - 完整的API文档 - [示例](./examples/) - 使用示例和模式 - [故障排除](./INSTALLATION.md#troubleshooting) - 常见问题和解决方案 ## 🤝 致谢 该项目基于并受以下项目启发： - **[VeNoMouS的CloudScraper](https://github.com/VeNoMouS/cloudscraper)** - 原始的Python实现 - **[cfbypass](https://github.com/VeNoMouS/cloudscraper)** - 为该封装程序提供支持的Python库 所有核心CloudFlare绕过功能的功劳归于原始的Python项目及其贡献者。 ## 📄 许可证 ISC许可证 - 有关详细信息，请参见 [LICENSE](./LICENSE) 文件。 ## 🐛 问题和贡献 发现了一个错误或有功能请求？请在GitHub上打开一个问题。欢迎贡献！ ## ⚠️ 免责声明 该库旨在用于合法的用例，例如网络爬虫、测试和API集成。请确保您遵守您交互的任何网站的服务条款，并尊重速率限制和robots.txt文件。