Python requests强制IPv4请求避坑指南

3步搞定Python requests强制IPv4请求避坑指南

一、 问题背景与核心需求

为什么在自动化脚本中需要强制 IPv4？

在近期开发的服务器访问控制脚本中，我们需要通过调用多个外部接口来获取出口 IP 地址，以便后续动态配置防火墙白名单规则。

以往该逻辑运行稳定，但近期由于操作系统或网络环境的 DNS 策略变更，requests 库默认开始优先尝试 IPv6 连接，导致获取到的地址不符合预期，进而引发白名单设置失败的问题。为了保障服务的兼容性与稳定性，我们必须在代码层面强制指定使用 IPv4 协议进行网络请求。

针对这一需求，网络上流传着多种配置方法，但在实际测试中往往因为版本差异或底层机制误解而报错。本文将梳理完整的排查过程，并提供唯一验证通过的稳定方案。

二、 常见踩坑方案与错误分析

误区一：直接传递 socket_family 参数

许多开发者会参考基础文档，尝试在初始化请求时直接传入地址族参数。相关代码如下：

import socket
import requests

# 设置socket的参数，强制使用IPv4
socket_af = socket.AF_INET
socket_family = socket.AF_INET

# 创建请求
response = requests.get("http://example.com", socket_family=socket_af, socket_type=socket_family)

# 打印响应内容
print(response.text)

该方法的理论依据是通过 socket.AF_INET 指定地址族。然而在实际执行中，requests 的核心会话类并未暴露这两个关键字参数，控制台会直接抛出 Session.request() got an unexpected keyword argument 'socket_family' 异常，导致脚本无法启动。

误区二：覆盖 allowed_gai_family 函数

部分技术社区建议通过重写 urllib3 内部的域名解析函数来绕过 IPv6。实现方式如下：

import socket
import requests.packages.urllib3.util.connection as urllib3_cn

def allowed_gai_family():
    \"\"\"
     https://github.com/shazow/urllib3/blob/master/urllib3/util/connection.py
    \"\"\"
    family = socket.AF_INET
    if urllib3_cn.HAS_IPV6:
        family = socket.AF_INET6 # force ipv6 only if it is available
    return family

urllib3_cn.allowed_gai_family = allowed_gai_family

虽然思路看似正确，但该写法忽略了底层函数的调用契约。替换后的对象类型与框架预期的可调用函数不匹配，执行时会触发 TypeError: 'AddressFamily' object is not callable 致命错误，中断整个请求流程。

三、 终极解决方案：修改 urllib3 全局配置

经过多轮对比测试，最稳定且无需复杂封装的方案是直接关闭 urllib3 的 IPv6 支持开关。该方法作用于请求生命周期之前，从根源切断 IPv6 解析路径。

# 在发起任何 requests 请求前执行此配置
requests.packages.urllib3.util.connection.HAS_IPV6 = False

只需在脚本初始化阶段添加上述单行代码，后续的 requests.get() 或 requests.post() 均会自动降级并仅使用 IPv4 建立 TCP 连接。该方案兼容性极强，完美适配 Python 3.x 环境及主流 urllib3 版本。

为了避免未来再次遇到同类网络协议冲突，建议在项目根目录统一维护此类全局配置。如需了解更多 Linux 系统管理与 Python 自动化运维技巧，欢迎访问 CyunZing的程序员修炼手册 获取更多实战教程。同时，你也可以点击 查看历史技术笔记 回顾更多开发踩坑记录。

• 部署时机：务必在导入 requests 后、发起首次请求前执行赋值操作。
• 适用范围：适用于所有基于 urllib3 封装的网络请求库（如 httpx、aiohttp 等需额外处理）。
• 调试建议：若仍需混合使用双栈协议，可考虑通过环境变量或自定义 Adapter 进行隔离。