PHP无内置IP白名单，应优先用$_SERVER['REMOTE_ADDR']，仅在可信反向代理（如Nginx配置real_ip相关指令）下才信任X-Real-IP；白名单校验需早返回、支持CIDR、统一入口拦截，避免依赖不可信HTTP头。
PHP 本身不内置 IP 白名单机制，必须手动实现；直接在 $_SERVER['REMOTE_ADDR'] 上做判断最轻量、最可控，但要注意代理场景下该值可能被伪造或替换。
怎么获取客户端真实 IP（避免被 X-Forwarded-For 欺骗）
不能无条件信任 $_SERVER['HTTP_X_FORWARDED_FOR'] 或 $_SERVER['HTTP_X_REAL_IP']，它们可被任意篡改。只在明确部署了可信反向代理（如 Nginx 配置了 set_real_ip_from）时才考虑使用 $_SERVER['REMOTE_ADDR'] 的替代值。
- 默认情况下，始终优先用
$_SERVER['REMOTE_ADDR'] - 若后端有 Nginx 且已配置
real_ip_header X-Real-IP;和set_real_ip_from 10.0.0.0/8;，则 PHP 中$_SERVER['REMOTE_ADDR']已是真实 IP，无需额外解析 - 禁止写类似
$ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'];这种“兜底”逻辑——攻击者发个X-Forwarded-For: 1.2.3.4就绕过了白名单
如何写一个安全的白名单校验函数
核心是：早返回、强匹配、支持 CIDR、不依赖外部配置文件（避免 include 失败导致放行）。
function isIpInWhitelist($ip, $whitelist = ['127.0.0.1', '192.168.1.0/24', '2001:db8::/32']) {
if (!$ip || !filter_var($ip, FILTER_VALIDATE_IP)) {
return false;
}
foreach ($whitelist as $rule) {
if (strpos($rule, '/') !== false) {
// CIDR 匹配
if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) && strpos($rule, ':') === false) {
if (ip_in_range($ip, $rule)) return true;
} elseif (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6) && strpos($rule, ':') !== false) {
if (ipv6_in_range($ip, $rule)) return true;
}
} else {
// 精确匹配
if ($ip === $rule) return true;
}
}
return false;
}
// 简化版 IPv4 CIDR 判断（不依赖 ext-bcmath）
function ip_in_range($ip, $range) {
[$subnet, $bits] = explode('/', $range);
$ip_long = ip2long($ip);
$subnet_long = ip2long($subnet);
$mask = -1 << (32 - $bits);
return ($ip_long & $mask) === ($subnet_long & $mask);
}
在哪里调用白名单检查最合适
放在所有业务逻辑之前，越早拦截越好。不推荐放在控制器方法里逐个判断，而应在入口统一处理。
立即学习“PHP免费学习笔记（深入）”；
- 对传统单入口（如
index.php），直接在文件开头加校验 - 对 Laravel / Symfony 等框架，应写成中间件（Middleware），并在 kernel 中注册到全局或特定路由组
- 避免在 model 或 service 层做 IP 校验——职责错位，且可能漏判
- 不要用
.htaccess或 Nginxallow/deny替代 PHP 层校验：它们无法区分同一 IP 下不同用户的会话状态，也无法和业务权限联动
常见踩坑点：IPv6、内网穿透、CDN 场景
白名单失效往往不是代码写错，而是环境理解偏差。
-
::1是 IPv6 的 localhost，和127.0.0.1不等价，白名单需显式包含 - 使用 frp / ngrok 等内网穿透工具时，
$_SERVER['REMOTE_ADDR']是穿透服务器 IP，不是用户真实 IP——此时白名单应针对穿透服务端 IP 设置，而非用户本地 IP - 接入 Cloudflare / 又拍云等 CDN 后，
REMOTE_ADDR变成 CDN 节点 IP；必须配合 CF 的CF-Connecting-IPheader 使用，且仅当确认该 header 由 CDN 签名保证不可篡改时才可信 - PHP-FPM + Nginx 组合下，若未配置
fastcgi_param REMOTE_ADDR $remote_addr;，可能导致$_SERVER['REMOTE_ADDR']错误为 127.0.0.1
真正难的不是写几行判断 IP 的代码，而是厘清请求链路上每一层谁在改写、谁在信任、谁在透传——漏掉任意一环，白名单就形同虚设。
