245 lines
10 KiB
Markdown
245 lines
10 KiB
Markdown
---
|
||
tags: [Nginx, 反向代理, 跨域, CORS, 运维]
|
||
create time: 2026-05-15 18:00
|
||
---
|
||
|
||
# Nginx 反向代理处理跨域
|
||
|
||
## 概述
|
||
|
||
本文档讲解如何利用 Nginx 反向代理解决浏览器端跨域（CORS）问题，从"最干净的方案"到"兜底方案"逐一展开，覆盖生产环境的典型场景。
|
||
|
||
> [!TIP] 核心思路
|
||
> 跨域是浏览器的安全策略，不是后端的限制。Nginx 做反向代理的核心思想：**让浏览器看到的地址和页面同源**，或者 **由 Nginx 在响应头中注入合法的 CORS header**。
|
||
|
||
## 正文
|
||
|
||
### 三种方案总览
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[遇到跨域问题] --> B{能否统一域名?}
|
||
B -- 能 --> C["方案一: 同源代理<br/>零跨域, 最干净"]
|
||
B -- 不能 --> D{后端已设 CORS header?}
|
||
D -- 能控制后端 --> E["方案二: Nginx 注入<br/>网关统一管理"]
|
||
D -- 无法改后端 --> F["方案三: 透传 Header<br/>保留上游配置"]
|
||
```
|
||
|
||
---
|
||
|
||
### 方案一：同源代理 — 从根本上消灭跨域（推荐）
|
||
|
||
请求的域名和页面域名完全一致，浏览器根本不认为这是跨域请求。
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name app.example.com;
|
||
|
||
# 前端静态资源
|
||
location / {
|
||
root /usr/share/nginx/html;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# API 代理 — 浏览器看到 /api/xxx，和页面同源
|
||
location /api/ {
|
||
proxy_pass http://backend:8080;
|
||
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;
|
||
}
|
||
}
|
||
```
|
||
|
||
**请求链路示意：**
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant B as 浏览器
|
||
participant N as Nginx
|
||
participant S as 后端服务
|
||
|
||
B->>N: GET /api/user （同源，无预检）
|
||
N->>S: GET /api/user
|
||
S-->>N: 200 OK (body)
|
||
N-->>B: 200 OK (body，不含 CORS header)
|
||
```
|
||
|
||
| 维度 | 说明 |
|
||
|------|------|
|
||
| 是否真正解决跨域 | ✅ 根本解决，浏览器不认为存在跨域 |
|
||
| Cookie / Session | 天然支持，无需额外配置 |
|
||
| 安全性 | 最高，不存在任何跨域风险 |
|
||
| 适用前提 | 你能控制前端部署域名 |
|
||
|
||
> **思考**：如果前端和后端分别部署在不同的子域名（如 `app.example.com` 和 `api.example.com`），这个方案还适用吗？不适用——这就是下面两种方案的用武之地。
|
||
|
||
---
|
||
|
||
### 方案二：Nginx 注入 CORS header（前后端无法同域时）
|
||
|
||
当 API 确实需要独立域名时，Nginx 充当"CORS 网关"，负责注入正确的响应头。
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name api.example.com;
|
||
|
||
# 允许的合法前端域名列表
|
||
set $cors_origin "";
|
||
|
||
if ($http_origin ~* "^https://(app\.example\.com|dev\.example\.com)$") {
|
||
set $cors_origin $http_origin;
|
||
}
|
||
|
||
location /api/ {
|
||
proxy_pass http://backend:8080;
|
||
|
||
# 白名单校验后的 Origin（未匹配则不注入，防止随意跨域）
|
||
add_header Access-Control-Allow-Origin $cors_origin always;
|
||
add_header Access-Control-Allow-Credentials "true" always;
|
||
add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-Token" always;
|
||
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
|
||
add_header Access-Control-Max-Age "3600" always;
|
||
add_header Access-Control-Expose-Headers "X-Total-Count, X-Request-Id" always;
|
||
|
||
# 预检请求直接响应 204
|
||
if ($request_method = OPTIONS) {
|
||
return 204;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**为什么这里用了正则白名单而不是直接回显 `$http_origin`？**
|
||
|
||
因为直接回显虽然省事，但意味着**任意域名**都能通过白名单校验拿到 CORS header，等同于变相开放。通过 `~*` 正则限定具体域名，是安全加固的一层。
|
||
|
||
#### 关键参数解释
|
||
|
||
| 参数 | 作用 | 注意事项 |
|
||
|------|------|---------|
|
||
| `add_header ... always` | `always` 确保即使后端返回 4xx/5xx 也加上 CORS header | 不加 `always` 时错误响应会丢失跨域信息 |
|
||
| `set $cors_origin ""` | 初始化为空，默认不允许跨域 | 这是一种"拒绝所有、放行白名单"的安全策略 |
|
||
| `if ($request_method = OPTIONS)` | 拦截预检请求，避免转发给后端 | Nginx 的 `if` 在此处使用是安全的（官方推荐用法） |
|
||
| `Access-Control-Max-Age` | 浏览器缓存预检结果的时间（秒） | 开发时建议设为 `0`，生产可设 `3600`~`86400` |
|
||
|
||
> [!WARNING] Credential 模式陷阱
|
||
> 如果设置了 `Access-Control-Allow-Credentials: true`，`Access-Control-Allow-Origin` **绝对不能是 `*`**。必须动态回显具体域名或走白名单——上面的配置已经通过白名单规避了这个问题。
|
||
|
||
---
|
||
|
||
### 方案三：透传后端 CORS header
|
||
|
||
当后端已经正确配置了 CORS header 时，**默认情况下 Nginx 不会移除这些响应头**，所以大多数场景你不需要任何额外配置。
|
||
|
||
> [!TIP] Nginx Header 传递规则（重点）
|
||
> - **无 `add_header` 时**：Nginx 完整透传上游响应头（包括 CORS header），且子级 `location` 会继承父级的 `add_header`。
|
||
> - **有 `add_header` 时**：Nginx **丢弃所有父级 `add_header` + 上游的 CORS header**。此时必须显式重新添加需要的头。
|
||
>
|
||
> 这是最常见的坑——你在某个 `location` 里加了一个自定义 header，结果发现 CORS header 突然消失了。
|
||
|
||
```nginx
|
||
# 如果你的 Nginx 配置里只有纯粹的 proxy_pass，无需额外操作：
|
||
location /api/ {
|
||
proxy_pass http://backend:8080;
|
||
}
|
||
```
|
||
|
||
但如果因为其他原因你已经在这个 `location` 里有 `add_header`（比如加了自定义 X-Custom-Header），就需要把 CORS header 一并补上：
|
||
|
||
```nginx
|
||
location /api/ {
|
||
proxy_pass http://backend:8080;
|
||
|
||
# 原有自定义 header
|
||
add_header X-Request-Id $request_id always;
|
||
|
||
# 补充 CORS header（否则会被 Nginx 吞掉）
|
||
proxy_hide_header Access-Control-Allow-Origin;
|
||
if ($http_origin ~* "^https://.+\.example\.com$") {
|
||
add_header Access-Control-Allow-Origin $http_origin always;
|
||
add_header Access-Control-Allow-Credentials "true" always;
|
||
}
|
||
}
|
||
```
|
||
|
||
| 做法 | 效果 | 适用场景 |
|
||
|------|------|---------|
|
||
| 不加任何 header | ✅ 完全透传后端 CORS | 后端已配置 CORS，Nginx 只做纯代理 |
|
||
| 仅加 `proxy_hide_header` | ⚠️ 不发送 CORS header | 需要临时屏蔽后端的 CORS |
|
||
| 加 `add_header` + `proxy_hide_header` | ✅ 手动重建 CORS | 已在该 location 有其他 header 需共存时 |
|
||
|
||
> [!NOTE] 最佳实践建议
|
||
> 如果后端和前端都在你的控制范围内，**统一将 CORS 配置放在后端中间件层**是最推荐的做法。Nginx 只负责路由转发，不做跨域决策——这样配置清晰、易于维护和审计。只有当你无法修改后端代码时，才需要在 Nginx 层"代劳"设置 CORS header（即回到方案二）。
|
||
|
||
---
|
||
|
||
### 常见陷阱与调试技巧
|
||
|
||
#### 陷阱一：`proxy_pass` 尾部斜杠的语义差异
|
||
|
||
`location /api/` 和 `proxy_pass` URL 末尾的 `/` 组合会产生不同行为，这是最容易踩的坑。
|
||
|
||
| `location` | `proxy_pass` 结尾 | 请求 `/api/user` → 转发给后端的路径 |
|
||
|------------|------------------|-----------------------------------|
|
||
| `/api/` | 无 `/`（`http://backend:8080`） | `/api/user`（原样转发） |
|
||
| `/api/` | 有 `/`（`http://backend:8080/`） | `/user`（`/api/` 被截断替换） |
|
||
|
||
> **记忆口诀**：`proxy_pass` URL 末尾有没有 `/`，决定了 location 匹配部分是否会被截断。
|
||
> - 没 `/` → 保持前端路径前缀不变（适合前后端共用同一个 API 前缀）
|
||
> - 有 `/` → 自动去掉 location 前缀（适合后端路由不需要前缀的场景）
|
||
|
||
#### 陷阱二：CORS header 突然消失 — Nginx 的继承规则
|
||
|
||
Nginx 的 `add_header` 有一个非常反直觉的行为：**一旦你在某个层级定义了 `add_header`，该层级及以下会丢弃所有父级的 header + 上游响应头。**
|
||
|
||
排查方法：
|
||
1. 用 `curl -vI https://api.example.com/api/test` 直接看响应头
|
||
2. 如果能看到 CORS header → 是 Nginx 配置层覆盖问题，回到方案三的规则修复
|
||
3. 如果看不到 → 检查后端实际返回了哪些 header（可能后端根本没设）
|
||
|
||
#### 陷阱三：`Access-Control-Allow-Headers` 遗漏字段
|
||
|
||
浏览器预检时会带上自定义 header（如 `X-Token`, `Authorization`），如果 Nginx 白名单中不包含这些字段，预检直接失败：
|
||
|
||
```bash
|
||
# 在控制台观察到的典型错误
|
||
# Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy:
|
||
# Request header field x-token is not allowed by Access-Control-Allow-Headers in preflight response.
|
||
```
|
||
|
||
解决：确保 `Access-Control-Allow-Headers` 包含前端所有可能发送的自定义 header。
|
||
|
||
#### 调试 Checklist
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[浏览器报 CORS 错误] --> B{curl 能正常访问?}
|
||
B -- No --> C["检查后端服务是否存活<br/>及健康检查路径"]
|
||
B -- Yes --> D{"Response Header 有 CORS?"}
|
||
D -- No --> E["后端未设置 CORS header<br/>→ 在后端中间件中添加"]
|
||
D -- Yes --> F{"curl 有但浏览器没有?"}
|
||
F -- Yes --> G["Nginx add_header 覆盖了上游<br/>→ 检查方案三的继承规则"]
|
||
F -- No --> H["检查 Response Status Code<br/>是否为 2xx/3xx?<br/>(4xx/5xx 需加 always)"]
|
||
```
|
||
|
||
---
|
||
|
||
### 对比总结
|
||
|
||
| 维度 | 方案一（同源代理） | 方案二（Nginx 注入） | 方案三（透传后端） |
|
||
|------|------------------|--------------------|-------------------|
|
||
| 是否真正解决跨域 | ✅ 根本解决 | ⚠️ 表面绕过 | ⚠️ 取决于后端 |
|
||
| 安全性 | 最高（无跨域） | 高（白名单可控） | 低（信任后端） |
|
||
| Cookie 支持 | ✅ 天然支持 | ✅ 配合白名单可用 | ✅ 天然支持 |
|
||
| 维护成本 | 低 | 中等（域名变更需改配置） | 最低 |
|
||
| 推荐优先级 | 🥇 首选 | 🥈 次选 | 🥉 兜底 |
|
||
|
||
## 关联笔记
|
||
|
||
- [[hzh/DEV/跨域问题调试]] — 跨域排查完整指南
|
||
- [[GIN/3-middleware/cors-registration-scope]] — 后端 Go/Gin 端 CORS 中间件配置参考
|