概述

CFspider 提供完整的同步 HTTP 请求功能，支持所有标准 HTTP 方法（GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH），语法与 requests 库完全兼容。

cfspider.get()

发送 GET 请求，用于获取资源。

函数签名

python
cfspider.get(
    url: str,
    cf_proxies: str = None,
    cf_workers: bool = True,
    http2: bool = False,
    impersonate: str = None,
    map_output: bool = False,
    map_file: str = "cfspider_map.html",
    stealth: bool = False,
    stealth_browser: str = 'chrome',
    delay: tuple = None,
    token: str = None,
    **kwargs
) -> CFSpiderResponse

参数说明

参数 类型 默认值 说明
url str 必填 目标 URL，必须包含协议（如 https://）
cf_proxies str None

代理地址，根据 cf_workers 参数有不同含义：

  • 当 cf_workers=True 时：CFspider Workers 地址（如 "https://your-workers.dev"）
  • 当 cf_workers=False 时：普通 HTTP/SOCKS5 代理（如 "http://127.0.0.1:8080"）
  • 不填写时：直接请求，不使用代理
cf_workers bool True 是否使用 CFspider Workers API。True 表示使用 Workers 代理，False 表示使用普通代理
http2 bool False 是否启用 HTTP/2 协议。需要安装 httpx[http2]。注意：http2 和 impersonate 不能同时使用
impersonate str None

TLS 指纹模拟，模拟真实浏览器的 TLS 握手特征。可选值：

  • chrome131, chrome124, chrome110 等（Chrome 浏览器）
  • safari18_0, safari17_0 等（Safari 浏览器）
  • firefox133, firefox120 等（Firefox 浏览器）
  • edge101, edge110 等（Edge 浏览器）

完整列表：cfspider.get_supported_browsers()
stealth bool False 是否启用隐身模式。True 时自动添加 15+ 个完整浏览器请求头，模拟真实浏览器访问
stealth_browser str 'chrome' 隐身模式使用的浏览器类型。可选值：chrome, firefox, safari, edge, chrome_mobile
delay tuple None 请求前的随机延迟范围（秒），如 (1, 3) 表示随机等待 1-3 秒。用于模拟人类行为，避免被反爬系统检测
token str None Workers API 鉴权 token。当 Workers 配置了 TOKEN 环境变量时必填
**kwargs dict -

其他参数，与 requests 库完全兼容：

  • params (dict): URL 查询参数
  • headers (dict): 自定义请求头（会与隐身模式头合并）
  • data (dict/str): 表单数据
  • json (dict): JSON 数据（自动设置 Content-Type）
  • cookies (dict): Cookie
  • timeout (int/float): 超时时间（秒），默认 30
  • allow_redirects (bool): 是否跟随重定向，默认 True
  • verify (bool): 是否验证 SSL 证书，默认 True

返回值

CFSpiderResponse

响应对象，包含以下属性：

  • text (str): 响应文本内容（自动解码）
  • content (bytes): 响应原始字节内容
  • status_code (int): HTTP 状态码（如 200, 404, 500）
  • headers (dict): 响应头字典
  • cookies: 响应 Cookie
  • url (str): 最终请求的 URL（跟随重定向后）
  • cf_colo (str): Cloudflare 节点代码（使用 Workers 时可用，如 NRT=东京, SIN=新加坡）
  • cf_ray (str): Cloudflare Ray ID，每个请求的唯一标识符

方法：

  • json(**kwargs): 将响应解析为 JSON
  • raise_for_status(): 当状态码非 2xx 时抛出 HTTPError

使用示例

基本 GET 请求

python
import cfspider

# 直接请求
response = cfspider.get("https://httpbin.org/ip")
print(response.json())
# {"origin": "1.2.3.4"}

使用 Workers 代理

python
response = cfspider.get(
    "https://httpbin.org/ip",
    cf_proxies="https://your-workers.dev"
)
print(response.cf_colo)  # NRT, SIN, LAX 等
print(response.cf_ray)   # 8a1b2c3d4e5f-NRT

带查询参数

python
response = cfspider.get(
    "https://httpbin.org/get",
    params={"key": "value", "page": 1}
)
# 实际请求: https://httpbin.org/get?key=value&page=1

自定义请求头

python
response = cfspider.get(
    "https://httpbin.org/headers",
    headers={
        "User-Agent": "MyApp/1.0",
        "X-Custom-Header": "value"
    }
)

启用隐身模式

python
response = cfspider.get(
    "https://example.com",
    stealth=True,
    stealth_browser='chrome'
)
# 自动添加 15+ 个完整浏览器请求头

TLS 指纹模拟

python
response = cfspider.get(
    "https://example.com",
    impersonate="chrome131"
)
# 模拟 Chrome 131 的 TLS 握手特征

请求延迟

python
response = cfspider.get(
    "https://example.com",
    delay=(1, 3)  # 随机等待 1-3 秒
)

cfspider.post()

发送 POST 请求，用于提交数据。

函数签名

python
cfspider.post(
    url: str,
    cf_proxies: str = None,
    cf_workers: bool = True,
    http2: bool = False,
    impersonate: str = None,
    map_output: bool = False,
    map_file: str = "cfspider_map.html",
    stealth: bool = False,
    stealth_browser: str = 'chrome',
    delay: tuple = None,
    token: str = None,
    **kwargs
) -> CFSpiderResponse

参数说明

参数与 cfspider.get() 相同，额外支持以下参数：

参数 类型 说明
data dict/str 表单数据。传入字典时自动编码为 application/x-www-form-urlencoded
json dict JSON 数据。自动设置 Content-Type: application/json
files dict 文件上传，格式与 requests 库相同

使用示例

发送 JSON 数据

python
response = cfspider.post(
    "https://httpbin.org/post",
    json={"name": "CFspider", "version": "1.8.0"}
)
# 自动设置 Content-Type: application/json

发送表单数据

python
response = cfspider.post(
    "https://httpbin.org/post",
    data={"username": "user", "password": "pass"}
)
# 自动编码为 application/x-www-form-urlencoded

发送原始字符串

python
response = cfspider.post(
    "https://httpbin.org/post",
    data="raw string data",
    headers={"Content-Type": "text/plain"}
)

其他 HTTP 方法

CFspider 还支持以下 HTTP 方法，用法与 get() 和 post() 相同：

cfspider.put()

发送 PUT 请求，用于更新资源。

python
response = cfspider.put(
    "https://api.example.com/resource/1",
    json={"name": "updated"}
)

cfspider.delete()

发送 DELETE 请求，用于删除资源。

python
response = cfspider.delete(
    "https://api.example.com/resource/1"
)

cfspider.head()

发送 HEAD 请求，只获取响应头，不获取响应体。

python
response = cfspider.head("https://example.com")
print(response.headers)  # 只包含响应头

cfspider.options()

发送 OPTIONS 请求，用于获取服务器支持的 HTTP 方法。

python
response = cfspider.options("https://api.example.com")
print(response.headers.get("Allow"))

cfspider.patch()

发送 PATCH 请求，用于部分更新资源。

python
response = cfspider.patch(
    "https://api.example.com/resource/1",
    json={"status": "active"}
)

cfspider.request()

通用请求函数，可以指定任意 HTTP 方法。

函数签名

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

使用示例

python
# 等同于 cfspider.get()
response = cfspider.request("GET", "https://example.com")

# 等同于 cfspider.post()
response = cfspider.request("POST", "https://api.example.com", json={...})

# 自定义方法
response = cfspider.request("CUSTOM", "https://api.example.com")

注意事项

http2 和 impersonate 不能同时使用

这两个参数使用不同的后端（httpx/curl_cffi），不能同时启用。

请求头优先级

隐身模式的请求头优先级：用户自定义 > stealth 默认头。自定义的 headers 会覆盖 stealth 生成的默认头。

Workers 代理的请求头传递

使用 Workers 代理时，自定义请求头通过 X-CFSpider-Header-* 传递到 Workers，Workers 会将其还原为原始请求头。