ThinkPHP获取真实IP与代理头配置指南

ThinkPHP 5/6 中 Request::ip() 返回 127.0.0.1 或内网 IP 是因未正确配置 trust_proxy 且前置代理（Nginx/SLB/CDN）未透传真实 IP；需在配置中显式设置可信代理段并确保 Web 服务器透传 X-Real-IP 或 X-Forwarded-For 头。

ThinkPHP 5/6 获取真实 IP 时 Request::ip() 返回 127.0.0.1 或内网地址

这是典型代理链未正确配置导致的。Nginx / SLB / CDN 等前置代理会把真实客户端 IP 放在 X-Forwarded-For 或 X-Real-IP 头里，但 ThinkPHP 默认只读 REMOTE_ADDR（即上一跳地址），而负载均衡器到 PHP 服务器这一跳通常是内网，所以拿到的是 127.0.0.1 或 10.x.x.x。

实操建议：

• 确认你的入口 Web 服务器（如 Nginx）已透传真实 IP，例如添加：

  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

• ThinkPHP 5.1+ 和 6.x 都支持通过 Request 的 ip() 方法指定信任的代理 IP 段，必须显式设置，否则不解析代理头
• 在 config/request.php（TP6）或 app/config.php（TP5）中配置：

  'trust_proxy' => ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '127.0.0.1'],

  注意：不能写成 'trust_proxy' => true，TP 不识别布尔值
• 如果用的是云厂商 SLB（如阿里云、腾讯云），它们通常只加 X-Forwarded-For，且可能只有一级代理，此时只需信任 SLB 的出口 IP 段（查厂商文档），避免盲目信任整个内网段，否则有伪造风险

TP6 中 Request::ip() 的 $type 参数失效或返回空

这个参数本意是让方法返回 IPv4 / IPv6 / 完整头字符串，但实际行为受 trust_proxy 配置强约束——如果没配信任代理，即使传了 'ipv4'，它也只返回 $_SERVER['REMOTE_ADDR']，不会去解析头。

常见错误现象：

• 调用 request()->ip('ipv4') 却返回空或 null
• request()->ip(false)（要求原始头）返回空数组，不是预期的 X-Forwarded-For 字符串

原因和对策：

• 先检查 trust_proxy 是否生效：用 var_dump(config('request.trust_proxy')) 确认值是数组且非空
• $type = false 表示“不格式化，直接取头”，但它只取 X-Real-IP（优先）或 X-Forwarded-For 第一个值，不是完整头内容；如需完整 X-Forwarded-For，应直接用 $request->header('x-forwarded-for')
• IPv6 场景下，若前端代理没透传 IPv6（比如只转了 IPv4 映射地址），ip('ipv6') 一定为空，别硬依赖

为什么开了 trust_proxy 还是拿不到真实 IP？检查这三处

配置写了、Nginx 也透传了，但日志里还是内网 IP——问题往往不在框架本身，而在中间环节。

• Nginx 的 proxy_pass 目标是否用了域名？如果是，且 DNS 解析出的是内网 VIP，那 $remote_addr 就是那个 VIP，不是客户端；应改用具体后端 IP 或确保 DNS 解析准确
• 是否启用了 FastCGI 缓存或 OPcache 导致配置未热更新？改完 config/request.php 后记得清缓存：php think clear:config（TP6）或删 runtime/cache/ 下文件（TP5）
• 云 WAF 或 CDN 开启了“隐藏真实 IP”开关（如 Cloudflare 的 “Anonymize IP”），它会主动抹掉 X-Forwarded-For，此时只能依赖 CF-Connecting-IP 这类厂商专用头，需额外在 trust_proxy 后手动处理

TP5.1 中自定义获取真实 IP 的安全兜底写法

官方 ip() 方法在复杂代理链下不够灵活，尤其当需要校验 IP 合法性、过滤私有地址、或兼容多头策略时，建议封装一层。

示例（放在公共函数或中间件中）：

function getRealIp($request)
{
    $ip = $request->header('x-real-ip', '');
    if (!$ip || in_array($ip, ['127.0.0.1', '::1'])) {
        $ip = $request->header('x-forwarded-for', '');
        $ip = explode(',', $ip)[0] ?? '';
    }
    // 基础合法性过滤，防伪造
    if (!filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE)) {
        $ip = $request->ip(); // fallback 到默认逻辑
    }
    return $ip;
}

注意点：

• 不要无条件信任 X-Forwarded-For 的第一个值，攻击者可伪造该头；务必结合 trust_proxy 配置做来源校验
• TP5.1 的 $request->ip() 内部已做基础过滤，但不校验私有地址，所以兜底函数里要补上 FILTER_FLAG_NO_PRIV_RANGE
• 如果业务对 IP 精度要求高（如风控、限流），建议在负载均衡层做 IP 白名单 + 头签名，PHP 层只做轻量校验

真实环境里，代理层级、头命名、IP 格式差异远比文档写的多，别迷信“配置完就自动好”，每次上线前用 curl 模拟不同头组合测一遍最稳妥。