Nginx跨域代理的完整排坑指南(从证书错误到CORS配置)
作者：码上有潜
一、背景与需求
最近在做一个项目，架构如下：
- 前端域名：
https://www.example.com - 第三方API：
https://thirdparty-api.example.net（不支持 CORS） - 目标：前端需要调用该第三方 API，但存在跨域问题
解决方案：使用 Nginx 做反向代理，将请求转发到自己的子域名 https://api.example.com，并在 Nginx 层添加 CORS 响应头。
预期请求链路：
浏览器 → api.example.com (Nginx) → thirdparty-api.example.net
本以为是个简单的配置，结果前后踩了 6 个坑，耗时整整一天。本文将完整记录排坑过程，希望对遇到类似问题的朋友有所帮助。
二、踩坑全记录
坑位1：SSL 证书域名不匹配
错误现象：
ERR_CERT_COMMON_NAME_INVALID
原因分析：api.example.com 使用了 www.example.com 的 SSL 证书，导致浏览器校验证书时发现域名不匹配。
解决方案：
为 api.example.com 申请独立的 SSL 证书：
certbot certonly --nginx -d api.example.com
教训：每个子域名都需要自己的证书，或使用通配符证书 *.example.com。
坑位2：CORS 预检请求失败
错误现象：
Access to fetch at 'https://api.example.com/...' from origin 'https://www.example.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
原因分析：
浏览器在发送实际请求前，会先发送一个 OPTIONS 预检请求。Nginx 没有正确处理这个请求，也没有返回必要的 CORS 响应头。
解决方案：
在 Nginx 配置中添加 CORS 头和 OPTIONS 请求处理：
location / {
# CORS 响应头
add_header 'Access-Control-Allow-Origin' 'https://www.example.com' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
# 处理预检请求
if ($request_method = 'OPTIONS') {
add_header 'Content-Length' 0;
add_header 'Content-Type' 'text/plain charset=utf-8';
return 204;
}
# 代理配置...
}
坑位3：add_header 语法错误
错误现象：
[emerg] "add_header" directive is not allowed here in /etc/nginx/conf.d/ssl.conf:47
原因分析：add_header 指令被放在了 Nginx 不允许的位置。这个指令只能出现在 http、server、location 块中，不能随意放置。
错误示例：
server {
# 正确位置
add_header 'Header1' 'value1' always;
location / {
# 正确位置
add_header 'Header2' 'value2' always;
}
}
# ❌ 错误：在 server/location 块外面
add_header 'Header3' 'value3' always;
解决方案：
确保所有 add_header 都在 server 或 location 块内部。
坑位4：Access-Control-Allow-Origin 重复
错误现象：
The 'Access-Control-Allow-Origin' header contains multiple values 'https://www.example.com, https://www.example.com', but only one is allowed.
原因分析：
Nginx 配置中 add_header 'Access-Control-Allow-Origin' ... 被写了两次，导致响应头中出现重复值。
解决方案：
检查配置文件，确保每个 CORS 头只添加一次。如果同时在 server 和 location 块中添加了，保留一处即可。
坑位5：代理 Host 头不正确
错误现象：
后端 API 返回 502 或 404，但直接访问后端 API 是正常的。
原因分析：
默认情况下 proxy_set_header Host $host 会将 Host 头设置为 api.example.com，而后端 API 可能期望的是自己的域名 thirdparty-api.example.net。
解决方案：
使用 $proxy_host 变量，它保存的是 proxy_pass 中指定的域名：
# ❌ 错误：Host 头变成 api.example.com proxy_set_header Host $host; # ✅ 正确：Host 头保持 thirdparty-api.example.net proxy_set_header Host $proxy_host;
坑位6：后端使用 HTTPS 导致证书问题
错误现象：
Nginx 代理到 https://thirdparty-api.example.net 时出现 SSL 错误。
原因分析：
Nginx 作为代理去访问 HTTPS 后端时，需要验证后端证书。如果后端证书有问题（自签名、过期、域名不匹配等），Nginx 会拒绝连接。
解决方案：
有两种方式：
方案A（推荐）：使用 HTTP 协议代理
# 如果后端支持 HTTP，直接用 HTTP proxy_pass http://thirdparty-api.example.net$request_uri;
方案B：忽略证书验证（仅临时使用）
proxy_pass https://thirdparty-api.example.net$request_uri; proxy_ssl_verify off; # 关闭证书验证
三、最终正确的配置
经过以上所有坑位的修复，最终配置如下：
server {
listen 443 ssl;
server_name api.example.com;
# DNS 解析器（使用域名代理时推荐添加）
resolver 114.114.114.114 223.5.5.5 valid=30s;
resolver_timeout 10s;
# SSL 证书（使用子域名自己的证书）
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
# HSTS 安全头
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
# SSL 配置
ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off;
client_max_body_size 100M;
location / {
# ========== CORS 配置 ==========
add_header 'Access-Control-Allow-Origin' 'https://www.example.com' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
# 处理预检请求
if ($request_method = 'OPTIONS') {
add_header 'Content-Length' 0;
add_header 'Content-Type' 'text/plain charset=utf-8';
return 204;
}
# ========== 代理配置 ==========
# 核心转发（使用 HTTP 避免后端证书问题）
proxy_pass http://thirdparty-api.example.net$request_uri;
# 关键：使用 $proxy_host 保持原始 Host
proxy_set_header Host $proxy_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;
# HTTP 1.1 支持
proxy_http_version 1.1;
proxy_set_header Connection "";
# 超时设置
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
# API 最佳实践：禁用缓存
proxy_buffering off;
proxy_cache off;
}
}
# HTTP 重定向到 HTTPS
server {
listen 80;
server_name api.example.com;
return 301 https://$server_name$request_uri;
}四、核心经验总结
1. 关于 SSL 证书
| 要点 | 说明 |
|---|---|
| 子域名需要独立证书 | api.example.com 不能使用 www.example.com 的证书 |
| 申请 命令 | certbot certonly --nginx -d api.example.com |
| 通配符证书 | *.example.com 可以覆盖所有子域名 |
2. 关于 CORS 配置
| 要点 | 说明 |
|---|---|
| 必须处理 OPTIONS | 浏览器预检请求需要返回 204 |
| 头不能重复 | Access-Control-Allow-Origin 只能出现一次 |
| 位置限制 | add_header 只能在 server/location 块内 |
3. 关于代理转发
| 要点 | 说明 |
|---|---|
Host 头用 $proxy_host | 保持后端期望的域名 |
添加 $request_uri | 完整传递请求路径 |
| 后端可以用 HTTP | 浏览器到 Nginx 需要 HTTPS，Nginx 到后端可以用 HTTP |
4. 调试技巧
# 测试 Nginx 配置语法 nginx -t # 查看错误日志 tail -f /var/log/nginx/error.log # 测试 CORS 响应头 curl -X OPTIONS https://api.example.com/api/test \ -H "Origin: https://www.example.com" \ -H "Access-Control-Request-Method: POST" \ -v 2>&1 | grep -i "access-control"
五、一个重要的认知
Postman 能请求成功 ≠ 浏览器能请求成功
| 工具 | 是否检查 CORS | 说明 |
|---|---|---|
| Postman | ❌ 不检查 | 桌面应用，不受浏览器安全策略限制 |
| curl | ❌ 不检查 | 命令行工具 |
| 浏览器 | ✅ 严格检查 | 为了用户安全，必须配置正确的 CORS |
这个认知能帮助您在调试时快速定位问题：Postman 通但浏览器不通 → 99% 是 CORS 配置问题。
六、架构总结
最终的成功架构：
浏览器 -----------(HTTPS)-----------> Nginx -----------(HTTP)-----------> 后端
(www.example.com) (api.example.com) (thirdparty-api)
↑ ↑ ↑
安全连接 SSL证书 + CORS头 内部通信
关键设计思想：
- 浏览器到 Nginx：必须 HTTPS，证书有效
- Nginx 到后端：可以用 HTTP，避免证书麻烦
- Nginx 层统一处理 CORS，后端无需改造
七、写在最后
这次排坑让我深刻体会到：
- Nginx 配置顺序和位置非常重要，一个小错误就能导致整个服务不可用
- CORS 不是后端的事，是 Nginx/网关层的事，统一处理比每个后端服务单独配置要优雅得多
- HTTPS 是端到端的，但中间代理可以用 HTTP 转发，不影响整体安全性
- 遇到问题先看日志，Nginx 的错误日志非常详细，能定位 90% 的问题
以上就是Nginx跨域代理的完整排坑指南(从证书错误到CORS配置)的详细内容，更多关于Nginx跨域代理排坑指南的资料请关注脚本之家其它相关文章！