API 文档 - CFspider Python 库

UUID 使用说明

不同的方法对 UUID 有不同的要求：

需要 UUID 的方法（使用 VLESS 协议，支持双层代理）

方法	UUID	双层代理	说明
`cfspider.get/post/...`	需要（可自动获取）	支持	基础 HTTP 方法
`cfspider.Session`	需要（可自动获取）	支持	会话管理
`cfspider.StealthSession`	需要（可自动获取）	支持	隐身会话
`cfspider.Browser`	需要（可自动获取）	支持	浏览器自动化
`cfspider.WebMirror`	需要（可自动获取）	支持	网页镜像

无需 UUID 的方法（使用 /proxy API）

方法	UUID	双层代理	说明
`cfspider.AsyncSession`	无需	HTTP 支持	异步会话
`cfspider.aget/apost/...`	无需	HTTP 支持	异步 HTTP 方法
`cfspider.impersonate_get/...`	无需	受限	TLS 指纹模拟
`cfspider.ImpersonateSession`	无需	受限	TLS 指纹会话

安装

bash

pip install cfspider

依赖要求：Python 3.8+

快速使用

Python

import cfspider

# 基本 GET 请求
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev"
)
print(response.json())

cfspider.make_workers() NEW

一键自动部署和管理 Cloudflare Workers，无需手动复制代码。

函数签名

Python

cfspider.make_workers(
    api_token: str,
    account_id: str,
    uuid: str = None,
    proxyip: str = None,
    key: str = None,
    accesskey: str = None,
    my_domain: str = None,
    auto_recreate: bool = True
) -> WorkersManager

参数

参数	类型	默认值	说明
`api_token`	str	必填	Cloudflare API Token（需要 Edit Workers 权限）
`account_id`	str	必填	Cloudflare Account ID
`uuid`	str	None	VLESS UUID（不填则自动生成）
`proxyip`	str	None	优选 IP（多个用逗号分隔）
`key`	str	None	X27CN 加密密钥
`accesskey`	str	None	访问密钥
`my_domain`	str	None	自定义域名（自动配置 DNS）
`auto_recreate`	bool	True	Workers 失效时自动重建

返回值

属性	类型	说明
`.url`	str	Workers URL（可直接用于 cf_proxies）
`.uuid`	str	VLESS UUID
`.healthy`	bool	健康状态
`.custom_url`	str	自定义域名 URL

示例

Python

import cfspider

# 基础用法 - 自动部署破皮版 Workers
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id"
)

# 使用 Workers 发起请求
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies=workers  # 直接传入 workers 对象
)
print(response.json())

# 高级用法 - 自定义配置
workers = cfspider.make_workers(
    api_token="your-api-token",
    account_id="your-account-id",
    uuid="custom-uuid",
    proxyip="1.1.1.1,8.8.8.8",
    my_domain="proxy.example.com"  # 自动配置自定义域名
)

print(workers.url)        # Workers URL
print(workers.uuid)       # UUID
print(workers.custom_url) # 自定义域名 URL

获取 API Token 和 Account ID

登录 Cloudflare Dashboard
Account ID：Workers & Pages → 右侧边栏
API Token：头像 → My Profile → API Tokens → Create Token → 选择 "Edit Cloudflare Workers"

cfspider.get()

发送 GET 请求。

函数签名

Python

cfspider.get(
    url: str,
    cf_proxies: str = None,
    uuid: str = None,
    static_ip: bool = False,
    two_proxy: str = None,
    stealth: bool = False,
    impersonate: str = None,
    **kwargs
) -> Response

参数

参数	类型	默认值	说明
`url`	str	必填	目标 URL（必须包含协议，如 https://）
`cf_proxies`	str	None	CFspider Workers 地址
`uuid`	str	None	VLESS UUID，不填写会自动获取
`static_ip`	bool	False	是否使用固定 IP 模式
`two_proxy`	str	None	第二层代理，格式：host:port:user:pass
`stealth`	bool	False	是否启用隐身模式（浏览器自动化）
`impersonate`	str	None	TLS 指纹模拟，如 chrome131
`**kwargs`	-	-	其他 requests 兼容参数

示例

Python

import cfspider

# 基本请求
response = cfspider.get("https://httpbin.org/ip", cf_proxies="https://your-workers.dev")

# 带 Headers
response = cfspider.get(
    "https://httpbin.org/headers",
    cf_proxies="https://your-workers.dev",
    headers={"User-Agent": "MyBot/1.0"}
)

# 固定 IP 模式
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev",
    static_ip=True
)

cfspider.post()

发送 POST 请求。

函数签名

Python

cfspider.post(
    url: str,
    data: dict = None,
    json: dict = None,
    cf_proxies: str = None,
    **kwargs
) -> Response

示例

Python

import cfspider

# 发送 JSON
response = cfspider.post(
    "https://httpbin.org/post",
    json={"key": "value"},
    cf_proxies="https://your-workers.dev"
)

# 发送表单
response = cfspider.post(
    "https://httpbin.org/post",
    data={"username": "test", "password": "123"},
    cf_proxies="https://your-workers.dev"
)

cfspider.request()

发送自定义 HTTP 请求。支持所有 HTTP 方法。

函数签名

Python

cfspider.request(
    method: str,
    url: str,
    **kwargs
) -> Response

支持的方法

GET
POST
PUT
DELETE
HEAD
OPTIONS
PATCH

cf_proxies 参数

指定 CFspider Workers 的地址。这是使用 CFspider 代理功能的必填参数。

格式

Python

cf_proxies = "https://your-workers.dev"
cf_proxies = "https://your-domain.com"

如果不填写此参数，cfspider 将直接发起请求，不使用代理。

uuid 参数

VLESS 协议的 UUID。用于认证 Workers 连接。

使用方式

Python

# 自动获取（Workers 使用默认 UUID）
response = cfspider.get(url, cf_proxies="https://your-workers.dev")

# 手动指定（Workers 配置了自定义 UUID）
response = cfspider.get(
    url,
    cf_proxies="https://your-workers.dev",
    uuid="your-custom-uuid"
)

static_ip 参数

控制是否使用固定 IP 模式。

值	行为
`False`（默认）	动态 IP 模式，每次请求自动获取新 IP
`True`	固定 IP 模式，复用同一连接保持 IP 不变

示例

Python

# 固定 IP 模式 - 多次请求保持同一 IP
for i in range(5):
    response = cfspider.get(
        "https://httpbin.org/ip",
        cf_proxies="https://your-workers.dev",
        static_ip=True
    )
    print(response.json())  # 每次输出相同 IP

two_proxy 参数

指定第二层代理，用于解决国内无法直连海外代理的问题。

格式

Python

# 完整格式（带认证）
two_proxy = "host:port:username:password"

# 简单格式（无认证）
two_proxy = "host:port"

流量路径

本地 → CF Workers (VLESS) → 第二层代理 → 目标网站

示例

Python

response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev",
    two_proxy="us.example.com:3010:username:password"
)
# 出口 IP 为第二层代理的 IP

proxies 参数

使用普通 HTTP/SOCKS5 代理，与 requests 库完全兼容。适用于已有海外代理且可以直连的情况。

格式

Python

# HTTP 代理
proxies = {
    "http": "http://user:pass@host:port",
    "https": "http://user:pass@host:port"
}

# SOCKS5 代理（需要 pip install requests[socks]）
proxies = {
    "http": "socks5://user:pass@host:port",
    "https": "socks5://user:pass@host:port"
}

示例

Python

import cfspider

# 直接使用普通代理（不经过 Workers）
response = cfspider.get(
    "https://httpbin.org/ip",
    proxies={
        "http": "http://user:pass@proxy.example.com:8080",
        "https": "http://user:pass@proxy.example.com:8080"
    }
)

代理参数对比

CFspider 支持三种代理方式，适用于不同场景：

参数	用途	格式示例
`cf_proxies`	CFspider Workers (VLESS 协议)	`"https://your-workers.dev"`
`proxies`	普通 HTTP/SOCKS5 代理	`{"http": "...", "https": "..."}`
`two_proxy`	双层代理（通过 Workers 转发）	`"host:port:user:pass"`

使用场景

场景	推荐方案
需要免费代理 IP 池	`cf_proxies` - 使用 Cloudflare WARP 出口
已有海外代理，可直连	`proxies` - 直接使用普通代理
已有海外代理，国内无法直连	`cf_proxies` + `two_proxy` - 通过 Workers 中转

完整示例

Python

import cfspider

# 方式 1: 使用 CFspider Workers（免费 IP 池）
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev"
)

# 方式 2: 使用普通代理（直连）
response = cfspider.get(
    "https://httpbin.org/ip",
    proxies={
        "http": "http://user:pass@proxy.example.com:8080",
        "https": "http://user:pass@proxy.example.com:8080"
    }
)

# 方式 3: 双层代理（国内无法直连时）
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev",
    two_proxy="us.example.com:3010:user:pass"
)

stealth 参数

启用隐身模式，使用 Playwright 进行浏览器自动化，绕过反爬虫检测。

示例

Python

response = cfspider.get(
    "https://example.com",
    cf_proxies="https://your-workers.dev",
    stealth=True,
    stealth_browser="chrome"  # 可选: chrome, firefox
)

注意：隐身模式需要安装 Playwright：playwright install

impersonate 参数

TLS 指纹模拟，伪装成指定浏览器的 TLS 特征。

可选值

chrome131 - Chrome 131
chrome126 - Chrome 126
safari18_0 - Safari 18.0
firefox133 - Firefox 133
edge101 - Edge 101

示例

Python

response = cfspider.get(
    "https://example.com",
    cf_proxies="https://your-workers.dev",
    impersonate="chrome131"
)

批量请求

使用 cfspider.batch() 进行批量请求。

Python

import cfspider

urls = [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3",
]

results = cfspider.batch(
    urls,
    cf_proxies="https://your-workers.dev",
    concurrency=5  # 并发数
)

for result in results:
    print(result.url, result.status_code)

网页镜像

使用 cfspider.mirror() 创建网页镜像。

Python

import cfspider

cfspider.mirror(
    "https://example.com",
    output_dir="./mirror",
    cf_proxies="https://your-workers.dev",
    depth=2  # 爬取深度
)

数据提取

使用 cfspider.extract() 提取页面数据。

Python

import cfspider

# CSS 选择器
data = cfspider.extract(
    "https://example.com",
    cf_proxies="https://your-workers.dev",
    css={
        "title": "h1::text",
        "links": "a::attr(href)"
    }
)

# XPath
data = cfspider.extract(
    "https://example.com",
    cf_proxies="https://your-workers.dev",
    xpath={
        "title": "//h1/text()",
        "links": "//a/@href"
    }
)

CFspider Python 库 API 文档

UUID 使用说明

需要 UUID 的方法（使用 VLESS 协议，支持双层代理）

无需 UUID 的方法（使用 /proxy API）

安装

快速使用

cfspider.make_workers() NEW

函数签名

参数

返回值

示例

获取 API Token 和 Account ID

cfspider.get()

函数签名

参数

示例

cfspider.post()

函数签名

示例

cfspider.request()

函数签名

支持的方法

cf_proxies 参数

格式

uuid 参数

使用方式

static_ip 参数

示例

two_proxy 参数

格式

流量路径

示例

proxies 参数

格式

示例

代理参数对比

使用场景

完整示例

stealth 参数

示例

impersonate 参数

可选值

示例

批量请求

网页镜像

数据提取