390 lines
15 KiB
Markdown
390 lines
15 KiB
Markdown
---
|
||
tags: [CORS, 跨域, 安全, HTTP, Web开发, 前后端分离]
|
||
create time: 2026-05-18 14:30
|
||
---
|
||
|
||
# 企业项目跨域问题解决方案
|
||
|
||
## 概述
|
||
|
||
跨域（Cross-Origin Resource Sharing, CORS）是前后端分离架构中最常见的网络限制问题。本文从浏览器同源策略出发，系统讲解跨域产生的原理、常见场景及完整解决方案，涵盖服务端配置、Nginx 反向代理和客户端降级方案，并附带 Go / Spring Boot / Node.js / Nginx 的实际代码示例。
|
||
|
||
> [!question] 思考：为什么浏览器要阻止跨域请求？
|
||
>
|
||
> 根源在于浏览器的「同源策略」（Same-Origin Policy）——它是一种安全机制，防止恶意网站读取你当前页面的 Cookie、LocalStorage 和 API 响应。但这一保护也带来了开发的困扰：**我们需要在保持安全的前提下，让不同域的服务之间正常通信。**
|
||
|
||
## 什么是跨域
|
||
|
||
### 同源的判定
|
||
|
||
两个 URL 只要 **协议（protocol）**、**域名（host）**、**端口（port）** 三者完全一致，就称为同源。任意一项不同，即为跨域。
|
||
|
||
| 当前 URL | 目标 URL | 是否跨域 | 原因 |
|
||
|----------|----------|----------|------|
|
||
| `https://api.example.com` | `https://app.example.com` | ✅ 跨域 | 域名不同 |
|
||
| `http://localhost:3000` | `http://localhost:8080` | ✅ 跨域 | 端口不同 |
|
||
| `https://example.com` | `http://example.com` | ✅ 跨域 | 协议不同 |
|
||
| `https://example.com/api` | `https://example.com/data` | ❌ 同域 | 仅路径不同（不算跨域） |
|
||
|
||
### 跨域的本质
|
||
|
||
跨域不是请求发不出去，而是 **浏览器拒绝接收响应**。实际过程如下：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["前端发起 AJAX / Fetch 请求"] --> B{"是否为跨域请求?"}
|
||
B -- '否' --> C["正常发送, 浏览器接收响应"]
|
||
B -- '是' --> D{"是否预检请求?"}
|
||
D -- '简单请求' --> E["直接发送请求"]
|
||
D -- '复杂请求' --> F["先发 OPTIONS 预检"]
|
||
F --> G{"服务端返回 200 + 正确 CORS 头?"}
|
||
G -- '是' --> E
|
||
G -- '否' --> H["浏览器拦截预检, 不发送真实请求"]
|
||
E --> I{"服务端是否携带 CORS 响应头?"}
|
||
I -- '是' --> C
|
||
I -- '否' --> J["浏览器拒绝响应, 控制台报错"]
|
||
```
|
||
|
||
关键结论：**服务器必须设置正确的 CORS 响应头，浏览器才会放行响应给 JavaScript。**
|
||
|
||
## 常见跨域场景
|
||
|
||
### 开发环境（本地 vs 后端）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
DevBrowser["浏览器<br/>localhost:5173"] --> Backend["Go API :8080<br/>（请求 /api/users）"]
|
||
```
|
||
|
||
这是开发阶段最常见的跨域场景——前端 dev server 跑在 `localhost:5173`，后端服务在 `:8080`，端口不同即触发跨域。
|
||
|
||
### 生产环境（多子域名）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
App["app.company.com"] --> Api["api.company.com<br/>（需配 CORS）"]
|
||
```
|
||
|
||
主站和 API 属于不同子域名，同样需要处理跨域。
|
||
|
||
### 嵌入场景（iframe / CDN）
|
||
|
||
- 页面加载第三方 CDN 上的静态资源（字体、JS、CSS）→ 通常没问题（GET 请求天然不受限）
|
||
- 页面内 iframe 向自身域名发 XHR 请求 → 受跨域限制
|
||
- 调用第三方 API（如支付回调、地图 SDK）→ 取决于对方是否支持 CORS
|
||
|
||
## 解决方案
|
||
|
||
### 方案一：服务端配置 CORS（推荐首选）
|
||
|
||
**适用场景**：自有服务端，可直接修改响应头。
|
||
|
||
#### Go (Gin 框架)
|
||
|
||
使用官方 `gin-contrib/cors` 中间件：
|
||
|
||
```go
|
||
import "github.com/gin-contrib/cors"
|
||
|
||
router := gin.Default()
|
||
|
||
config := cors.DefaultConfig()
|
||
config.AllowOrigins = []string{"https://app.example.com"} // 明确允许的源
|
||
config.AllowMethods = []string{"GET", "POST", "PUT", "DELETE"}
|
||
config.AllowHeaders = []string{"Origin", "Content-Type", "Authorization"}
|
||
config.AllowCredentials = true // 携带 Cookie 时必须设为 true
|
||
config.MaxAge = 12 * time.Hour // 预检请求缓存时长
|
||
|
||
router.Use(cors.New(config))
|
||
```
|
||
|
||
`AllowOrigins` 白名单是安全的第一道防线——它告诉浏览器"只有这些域名可以读取我的接口数据"。`AllowCredentials` 用于允许携带 Cookie（如登录态），但配合白名单使用，绝不可与通配符 `*` 同时出现。`MaxAge` 设置预检请求在浏览器的缓存时长，减少不必要的 OPTIONS 请求。
|
||
|
||
> [!tip] 生产环境安全要点
|
||
>
|
||
> - **不要用 `AllowOrigins = ["*"]` 配合 `AllowCredentials = true`**，这会引发 panic 或无效配置。
|
||
> - 应显式列出允许的前端域名白名单，避免恶意站点劫持接口。
|
||
> - 如需支持多个前端域名，可从环境变量或配置中心动态读取。
|
||
|
||
#### Java (Spring Boot)
|
||
|
||
Spring Boot 提供了多种 CORS 配置方式：
|
||
|
||
**全局配置（实现 WebMvcConfigurer）：**
|
||
|
||
```java
|
||
@Configuration
|
||
public class CorsConfig implements WebMvcConfigurer {
|
||
|
||
@Override
|
||
public void addCorsMappings(CorsRegistry registry) {
|
||
registry.addMapping("/api/**") // 生效的路径
|
||
.allowedOrigins("https://app.example.com")
|
||
.allowedMethods("GET", "POST", "PUT", "DELETE")
|
||
.allowedHeaders("*")
|
||
.allowCredentials(true)
|
||
.maxAge(3600); // 预检缓存 1 小时
|
||
}
|
||
}
|
||
```
|
||
|
||
**注解级别（细粒度控制单个 Controller）：**
|
||
|
||
```java
|
||
@CrossOrigin(origins = "https://app.example.com", maxAge = 3600)
|
||
@RestController
|
||
@RequestMapping("/api/admin")
|
||
public class AdminController { ... }
|
||
```
|
||
|
||
#### Node.js (Express)
|
||
|
||
```js
|
||
const cors = require('cors');
|
||
|
||
app.use(cors({
|
||
origin: ['https://app.example.com', 'https://admin.example.com'],
|
||
credentials: true,
|
||
methods: ['GET', 'POST', 'PUT', 'DELETE'],
|
||
allowedHeaders: ['Content-Type', 'Authorization'],
|
||
}));
|
||
```
|
||
|
||
此配置传入 Express 的中间件链中，会对所有路由生效。如需限定路径范围，可改为 `app.use('/api', cors(config))` 。与 Go / Java 方案相比，Node.js 方案最轻量——无需额外注解或配置类，只需在启动时注册一次即可。
|
||
|
||
### 方案二：Nginx 反向代理（零侵入）
|
||
|
||
**适用场景**：无法修改后端代码、多语言混合后端统一治理、隐藏后端地址提升安全。
|
||
|
||
核心思路：让前端访问 Nginx 的 `/api` 路径，Nginx 把请求转发到后端，同时注入 CORS 响应头。
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl;
|
||
server_name app.example.com;
|
||
|
||
# --- 前端静态资源 ---
|
||
location / {
|
||
root /usr/share/nginx/html;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# --- Location 1: OPTIONS 预检请求（直接返回，不通后端）---
|
||
location ~ ^/api/.*$ {
|
||
if ($request_method = 'OPTIONS') {
|
||
add_header 'Access-Control-Allow-Origin' '$http_origin';
|
||
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
|
||
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';
|
||
add_header 'Access-Control-Max-Age' 1728000;
|
||
add_header 'Content-Type' 'text/plain; charset=utf-8';
|
||
add_header 'Content-Length' 0;
|
||
return 204;
|
||
}
|
||
}
|
||
|
||
# --- Location 2: 真实请求（反向代理 + CORS 头）---
|
||
location /api/ {
|
||
add_header 'Access-Control-Allow-Origin' '$http_origin' always;
|
||
add_header 'Access-Control-Allow-Credentials' 'true' always;
|
||
add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
|
||
|
||
proxy_pass http://backend_server:8080;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!warning] Nginx 注意事项
|
||
>
|
||
> - `if ($request_method = 'OPTIONS')` 中的 `if` 在 Nginx 中有陷阱，但它在这里是安全的用法（只操作 header）。
|
||
> - `always` 参数确保即使错误响应（4xx / 5xx）也带上 CORS 头。
|
||
> - `return 204` 直接返回空体，避免 OPTIONS 请求打到后端增加负载。
|
||
|
||
### Nginx 方案的架构图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Browser["浏览器 app.example.com"] --> Nginx["Nginx 443<br/>（GET /api/users）"]
|
||
Nginx --> Backend["后端 :8080<br/>（proxy_pass）"]
|
||
Backend --> JSONResponse["JSON 响应"]
|
||
Nginx --> BrowserReply["返回含 CORS 头的<br/>JSON 响应"]
|
||
BrowserReply --> Browser
|
||
```
|
||
|
||
对比之下，不加 Nginx 时的直连模式：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Browser["浏览器<br/>app.example.com<br/><b>❌ 跨域 + 无 CORS 头</b>"] --> Backend["后端 api.example.com:8080"]
|
||
```
|
||
|
||
此时浏览器直接访问后端接口，因域名和端口均不同触发跨域限制，且服务端未配置 CORS 头，浏览器拦截响应。
|
||
|
||
### 方案三：开发期 Vite/Webpack Proxy（开发专用）
|
||
|
||
**适用场景**：本地开发时绕过跨域，上线后由 Nginx 处理。
|
||
|
||
#### Vite 配置 (`vite.config.ts`)
|
||
|
||
```ts
|
||
import { defineConfig } from 'vite';
|
||
|
||
export default defineConfig({
|
||
server: {
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://localhost:8080', // 后端地址
|
||
changeOrigin: true, // 改写 Host 头
|
||
secure: false, // 自签证书时可关闭校验
|
||
},
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
这样前端发 `fetch('/api/users')` 时，Vite dev server 会转发到 `http://localhost:8080/api/users`，因为是同源请求，不存在跨域。
|
||
|
||
#### Webpack (`vue.config.js` / `webpack.config.js`)
|
||
|
||
```js
|
||
module.exports = {
|
||
devServer: {
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://localhost:8080',
|
||
changeOrigin: true,
|
||
},
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
`changeOrigin: true` 会将被代理请求的 Host 头改为后端地址，这对于某些依赖 Host 做鉴权的后端服务是必要的。Webpack proxy 同样只在本地开发生效，生产环境仍需 Nginx 或 CORS 中间件配合。
|
||
|
||
> [!info] Vite/Webpack Proxy 与正式方案的区别
|
||
>
|
||
> | | 开发 Proxy | Nginx / 服务端 CORS |
|
||
> |---|---|---|
|
||
> | 用途 | 仅限本地开发 | 生产环境 |
|
||
> | 需要后端改吗 | 不需要 | 不需要（Nginx）/ 需要（服务端） |
|
||
> | HTTPS 支持 | 需额外配置 | 原生支持 |
|
||
> | 部署复杂度 | 无 | 低 |
|
||
|
||
### 方案四：JSONP / 服务端重定向（历史方案，了解即可）
|
||
|
||
#### JSONP
|
||
|
||
利用 `<script>` 标签不受同源策略限制的特性，通过回调函数接收数据。仅支持 GET，且存在 XSS 风险，已属历史方案。
|
||
|
||
**原理**：后端返回 `callbackName(data)` 这样的 JavaScript 代码，前端动态插入 `<script>` 标签触发执行。
|
||
|
||
```html
|
||
<!-- 前端 -->
|
||
<script>
|
||
function jsonpCallback(data) {
|
||
console.log(data); // 拿到后端返回的数据
|
||
}
|
||
</script>
|
||
<script src="https://api.example.com/data?callback=jsonpCallback"></script>
|
||
```
|
||
|
||
```go
|
||
// Go 后端示例
|
||
func JSONPHandler(w http.ResponseWriter, r *http.Request) {
|
||
callback := r.URL.Query().Get("callback")
|
||
data := `{"name": "John", "age": 30}`
|
||
w.Header().Set("Content-Type", "application/javascript")
|
||
fmt.Fprintf(w, "%s(%s)", callback, data)
|
||
}
|
||
```
|
||
|
||
> [!note] JSONP 的局限性
|
||
>
|
||
> - **只支持 GET**——POST/PUT/DELETE 等无法实现
|
||
> - **无错误处理**——脚本加载失败时只能通过 `onerror` 粗略捕获
|
||
> - **安全风险**——任何提供 JSONP 的接口都可能被恶意站点调用，需额外做 Referer 校验
|
||
> - **已被 CORS 全面取代**——现代浏览器全部支持 CORS，新项目不应考虑此方案
|
||
|
||
#### 服务端重定向
|
||
|
||
后端自己调后端，前端只请求同源接口。适合微服务间调用，但不解决浏览器侧跨域。
|
||
|
||
## 进阶话题
|
||
|
||
### 带凭据的请求（Cookie / Authorization Header）
|
||
|
||
当 `withCredentials: true`（fetch）或 `xhr.withCredentials = true`（XMLHttpRequest）时：
|
||
|
||
1. 服务端 `Access-Control-Allow-Origin` **不能**为 `*`，必须是具体域名
|
||
2. 服务端需设置 `Access-Control-Allow-Credentials: true`
|
||
3. 浏览器会在请求中带上 Cookie
|
||
|
||
```ts
|
||
// 前端 fetch 带 Cookie
|
||
fetch('https://api.example.com/user/profile', {
|
||
method: 'GET',
|
||
credentials: 'include', // 关键：带上 Cookie
|
||
headers: { 'Authorization': 'Bearer xxx' },
|
||
});
|
||
```
|
||
|
||
`credentials: 'include'` 是让浏览器发送 Cookie 的关键。如果只设 `credentials` 而不配服务端 `Access-Control-Allow-Credentials: true`，或者后端 `Allow-Origin` 仍为 `*`，请求同样会被拦截——这是一个"双方都满足才能通过"的条件。
|
||
|
||
### 预检请求的优化
|
||
|
||
复杂请求（自定义头、PUT/DELETE 等）会先发送 `OPTIONS` 预检。可通过以下方式减少开销：
|
||
|
||
#### Max-Age 缓存的影响
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["Max-Age = 0<br/><b>每次请求都发 OPTIONS</b>"] --> B["⚠️ 高延迟，<br/>服务器压力大"]
|
||
C["Max-Age = 86400<br/><b>24小时内复用预检结果</b>"] --> D["✅ 首慢后续快，<br/>负载低"]
|
||
```
|
||
|
||
#### 设置方式
|
||
|
||
服务端或 Nginx 中设置响应头即可：
|
||
|
||
- `Access-Control-Max-Age: 86400` — 缓存 24 小时，超过需重新预检
|
||
- 一般建议设为 **1 天到 7 天**，具体取决于接口变更频率
|
||
|
||
### RESTful 动词与预检的关系
|
||
|
||
| 方法 | 是否可能预检 | 原因 |
|
||
|------|-------------|------|
|
||
| GET | ❌ 不会 | 简单请求 |
|
||
| POST (application/x-www-form-urlencoded / multipart/form-data / text/plain) | ❌ 可能不会 | Content-Type 在白名单内 |
|
||
| POST (application/json) | ✅ 会预检 | Content-Type 不在简单请求白名单 |
|
||
| PUT / DELETE / PATCH | ✅ 会预检 | 不在简单请求方法的白名单 |
|
||
|
||
### 常见问题排查清单
|
||
|
||
> [!check] 跨域问题排查流程
|
||
>
|
||
> 1. **确认跨域类型** — 打开浏览器 DevTools → Network，看请求状态码是 `200` 还是 `cors error`
|
||
> 2. **检查请求头** — Request Headers 里是否有 `Origin`，值是否正确
|
||
> 3. **检查响应头** — Response Headers 中是否有 `Access-Control-Allow-Origin`，值和前端域名匹配吗
|
||
> 4. **区分简单请求和预检** — 有无单独的 `OPTIONS` 请求发出？OPTIONS 返回什么？
|
||
> 5. **credentials 场景** — 是否同时满足了 `具体 Allow-Origin` + `Allow-Credentials: true`
|
||
> 6. **多级代理链路** — 经过网关 / WAF / CDN 时，确认每一层都不删除 CORS 头
|
||
|
||
## 方案选型速查表
|
||
|
||
| 场景 | 推荐方案 | 理由 |
|
||
|------|----------|------|
|
||
| 前后端同公司，后端可改 | 服务端 CORS 中间件 | 最直接，语义清晰 |
|
||
| 多语言后端 / 不便改代码 | Nginx 反代注入 CORS 头 | 统一治理，零侵入 |
|
||
| 本地开发 | Vite/Webpack Proxy | 开发体验最佳 |
|
||
| 生产环境隐藏后端 IP | Nginx 反代 | 安全 + 跨域双收益 |
|
||
| 纯静态页调用第三方公开 API | 让第三方配好 CORS | 自身无能为力 |
|
||
|
||
## 关联笔记
|
||
|
||
- [[hhs/GIN/3-middleware/cors-registration-scope/cors-preflight]] — Gin 框架下预检请求的详细机制
|
||
- [[hhs/DEV/Nginx/Nginx]] — Nginx 配置速查，含反向代理、负载均衡等
|
||
- [[hhs/DEV/XSS与CSRF攻击/XSS与CSRF攻击]] — 同源策略是防御 XSS/CSRF 的基础
|
||
- [[03-服务端鉴权认证方案]] — Cookie / Session 鉴权与 CORS 凭据的配合
|
||
- [[hhs/MS/02-服务治理/01-API网关]] — 微服务架构中通过 API 网关统一处理跨域
|