> For the complete documentation index, see [llms.txt](https://docs.ipwo.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipwo.net/ji-cheng-jiao-cheng/gong-ju-yu-dai-li-ruan-jian/ru-he-wei-curlcffi-she-zhi-ipwo-dai-li.md).

# 如何为 curl\_cffi 设置 IPWO 代理

curl\_cffi 是一个基于 libcurl 的 Python HTTP 客户端，提供了与 Requests 类似的 API，并支持浏览器指纹模拟（Browser Impersonation）、HTTP/2 等特性，因此广泛应用于数据采集、自动化测试和反爬场景。curl\_cffi 支持通过 `proxy` 或 `proxies` 参数配置代理，可以方便地集成 IPWO 动态住宅代理。

***

### 一、准备工作

开始配置前，请确保已完成以下准备：

* 已安装 Python 3
* 已安装 curl\_cffi
* 已开通[ IPWO 动态住宅代理](/dai-li-chan-pin/dong-tai-zhu-zhai-dai-li.md)
* 已创建 Zone
* 已获取代理用户名、密码和代理地址

如果尚未安装 curl\_cffi，可执行：

```bash
pip install curl_cffi
```

***

### 二、配置 IPWO 代理

curl\_cffi 推荐使用 `proxy` 参数配置代理。

示例代码：

```python
from curl_cffi import requests

proxy = "http://username_custom_zone_us:password@us.ipwo.net:7878"

response = requests.get(
    "https://ipinfo.io/json",
    proxy=proxy,
    timeout=15
)

print(response.text)
```

请根据自己的账户信息替换以下内容：

| 参数                         | 说明      |
| -------------------------- | ------- |
| username\_custom\_zone\_us | 代理用户名   |
| password                   | 代理密码    |
| us.ipwo.net                | 代理服务器地址 |
| 7878                       | 代理端口    |

官方建议：如果 HTTP 和 HTTPS 使用同一个代理，优先使用 `proxy` 参数；只有在需要分别指定不同代理时，再使用 `proxies` 参数。

***

### 三、使用 proxies 配置代理（可选）

如果需要兼容 Requests 的写法，也可以使用 `proxies` 参数。

示例：

```python
from curl_cffi import requests

proxies = {
    "http": "http://username_custom_zone_us:password@us.ipwo.net:7878",
    "https": "http://username_custom_zone_us:password@us.ipwo.net:7878"
}

response = requests.get(
    "https://ipinfo.io/json",
    proxies=proxies
)

print(response.text)
```

***

### 四、测试代理是否生效

建议首次配置完成后，先访问 IP 检测接口验证代理是否生效。

示例：

```python
from curl_cffi import requests

proxy = "http://username_custom_zone_us:password@us.ipwo.net:7878"

response = requests.get(
    "https://ipinfo.io/json",
    proxy=proxy
)

print(response.json())
```

正常情况下会返回类似结果：

```json
{
  "ip": "203.0.113.10",
  "country": "US"
}
```

如果返回的公网 IP 已发生变化，并且国家地区符合配置，则说明代理已经配置成功。

***

### 五、浏览器指纹模拟（可选）

curl\_cffi 支持模拟主流浏览器请求特征，可用于部分需要浏览器指纹的访问场景。

示例：

```python
from curl_cffi import requests

response = requests.get(
    "https://ipinfo.io/json",
    proxy="http://username_custom_zone_us:password@us.ipwo.net:7878",
    impersonate="chrome"
)

print(response.text)
```

如果目标网站对请求指纹有要求，可根据实际情况选择支持的浏览器类型。

***

### 六、固定 Session（可选）

如果业务需要保持同一个出口 IP，可以在用户名中增加 Session 参数。

例如：

```
username_custom_zone_us_session_123456
```

使用相同的 Session 发起请求时，会尽可能保持同一个住宅 IP，适用于账号登录、长期会话和连续采集等业务场景。

更多内容可参考《[Session 使用说明](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/session-shi-yong-shuo-ming.md)》。

***

### 七、使用建议

为了获得更稳定的请求效果，建议：

* 为请求设置合理的超时时间
* 登录类业务建议使用固定 Session
* 根据目标业务选择对应国家地区
* 控制请求频率，避免短时间大量请求
* 优先使用 `proxy` 参数配置代理
* 首次接入时先验证代理是否正常，再启用浏览器指纹模拟

***

### 八、常见问题

#### [返回 407](/gu-zhang-pai-chu/dai-li-407-cuo-wu.md) Proxy Authentication Required

请检查：

* 用户名是否正确
* 密码是否正确
* Zone 是否配置正确

***

#### [请求超时（Timeout）](/gu-zhang-pai-chu/chao-shi-timeout.md)

请检查：

* 当前网络是否能够访问代理节点
* timeout 设置是否过低
* 网络连接是否稳定

***

#### 返回的 IP 未变化

请确认：

* 是否正确配置 `proxy` 或 `proxies`
* 用户名、密码是否填写正确
* 请求是否真正通过代理发送

***

#### HTTPS 请求失败

请检查代理地址是否使用 **HTTP** 协议，例如：

```
http://us.ipwo.net:7878
```

即使访问的是 HTTPS 网站，代理地址通常仍然使用 `http://` 前缀，这是 curl\_cffi 官方文档特别提醒的常见问题。

***

### 九、相关文章

* [如何使用 cURL 配置 IPWO 代理](/ji-cheng-jiao-cheng/gong-ju-yu-dai-li-ruan-jian/ru-he-shi-yong-curl-pei-zhi-ipwo-dai-li.md)
* [如何为 aiohttp 设置 IPWO 代理](/ji-cheng-jiao-cheng/gong-ju-yu-dai-li-ruan-jian/ru-he-wei-aiohttp-she-zhi-ipwo-dai-li.md)
* [如何为 Beautiful Soup 设置 IPWO 代理](/ji-cheng-jiao-cheng/gong-ju-yu-dai-li-ruan-jian/ru-he-wei-beautiful-soup-she-zhi-ipwo-dai-li.md)
* [如何为 urllib3 设置 IPWO 代理](/ji-cheng-jiao-cheng/gong-ju-yu-dai-li-ruan-jian/ru-he-wei-urllib3-she-zhi-ipwo-dai-li.md)
* [Session 使用说明](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/session-shi-yong-shuo-ming.md)
* [请求最佳实践](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/qing-qiu-zui-jia-shi-jian.md)
* [如何检测代理是否生效](/dai-li-jian-ce-yu-yin-si-an-quan/ru-he-jian-ce-dai-li-shi-fou-sheng-xiao.md)