正确配置Nginx透传真实IP需三行：proxy_set_header X-Real-IP $remote_addr; X-Forwarded-For $proxy_add_x_forwarded_for; X-Forwarded-Proto $scheme;Next.js中需手动读取这些header获取真实IP。
Next.js 应用通常运行在 Node.js 服务（如 next start）之上，前端由 Nginx 反向代理。若不正确配置请求头，后端拿到的客户端 IP 会是 Nginx 的本地地址（如 127.0.0.1），而非真实访问者 IP——这对日志记录、风控、地理限制等场景至关重要。关键在于用 proxy_set_header 正确透传真实 IP。
必须设置的三个核心 header
Nginx 需主动将客户端真实 IP 和协议信息注入请求头，Next.js 后端（或中间件）才能读取。以下三行缺一不可：
-
proxy_set_header X-Real-IP $remote_addr;—— 直接传递最外层客户端 IP（适用于单层代理） -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 追加 IP 到已有的X-Forwarded-For链（支持多级代理） -
proxy_set_header X-Forwarded-Proto $scheme;—— 告知后端原始请求是http还是https，避免混合内容或重定向错误
location 块中的完整代理配置示例
假设 Next.js 服务监听 localhost:3000，Nginx 配置应类似如下（注意位置和上下文）：
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
⚠️ 注意：proxy_set_header 必须写在 location 或 server 块内，不能只放在 http 全局块（除非你确认所有代理都需一致行为）。
Next.js 中如何获取真实 IP
Next.js App Router 或 Pages Router 默认不自动解析这些 header。你需要手动读取：
- 在 API Route 中：
req.headers["x-real-ip"]或req.headers["x-forwarded-for"]（后者可能含多个 IP，取第一个） - 使用中间件（
middleware.ts）时，可通过request.headers.get("x-real-ip")获取 - 若部署在 Vercel 等平台，其已内置处理；但自托管时必须依赖 Nginx 透传 + 自行解析
安全提醒：防止 IP 伪造
X-Forwarded-For 可被客户端伪造，因此仅在可信代理链中使用。确保：
- Nginx 是唯一入口（前置无其他未受信代理）
- 若存在 CDN（如 Cloudflare），应启用「True-Client-IP」或使用
set_real_ip_from指令信任 CDN 回源 IP 段，并配置real_ip_header - 生产环境禁用
proxy_set_header X-Forwarded-For $remote_addr;（覆盖式写法），始终用$proxy_add_x_forwarded_for追加
透传真实 IP 不是“加几行就完事”，而是代理链、header 命名、后端解析三者协同的结果。配对验证：curl 请求时加 -H "X-Forwarded-For: 1.2.3.4"，再看日志是否仍显示真实客户端 IP，就能快速定位问题环节。
