Nginx反向代理CORS配置完整教程：解决代理后跨域失效的实战指南

一、为什么反向代理后CORS配置会失效？

很多同学在配置Nginx反向代理时都会遇到一个诡异的问题：直接访问后端服务时跨域完全正常，加上Nginx反向代理后就突然报跨域错误，或者前端请求时偶尔跨域失败、偶尔成功。这个问题的核心原因基本都和Nginx的响应头处理机制有关，常见的有以下3种：

• 后端服务也返回了CORS头，导致Nginx配置被覆盖

  Nginx的add_header指令默认不会覆盖后端返回的同名响应头，如果后端服务（比如Node.js、Java应用）自身也配置了CORS头，那么后端返回的头会优先生效，导致你在Nginx里配置的跨域规则失效。比如你Nginx里配了允许特定域名，后端返回了Access-Control-Allow-Origin: *，最终生效的会是后端的配置。

• add_header作用域配置错误

  add_header指令遵循继承规则，但只在当前作用域和未显式覆盖的子作用域生效。如果你把CORS配置写在了server块，但处理请求的location块里显式写了其他add_header指令，那么server块的CORS配置会被完全覆盖，不会生效。另外如果location块里用了proxy_hide_header指令，也可能误隐藏掉CORS相关响应头。

• OPTIONS预检请求未被正确处理

  当前端请求是复杂请求（比如带自定义Header、使用PUT/DELETE方法、Content-Type为application/json）时，浏览器会先发送一个OPTIONS预检请求，确认后端允许跨域后才会发送正式请求。如果Nginx没有正确处理OPTIONS请求，导致预检失败，那么后续的所有请求都会被浏览器拦截，表现为CORS配置失效。

二、Nginx反向代理CORS完整配置步骤（生产级可用）

下面是基于生产环境验证的完整配置流程，适用于90%以上的反向代理跨域场景：

步骤1：server块配置全局CORS基础头

在server块下添加全局CORS配置，确保所有location都能继承基础规则，同时注意要加always参数：

server {
    listen 80;
    server_name your-domain.com;

    # 全局CORS基础配置，always参数确保所有响应码都返回CORS头
    add_header Access-Control-Allow-Origin $cors_origin always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS, PATCH" always;
    add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With, X-Custom-Header" always;
    add_header Access-Control-Allow-Credentials "true" always;
    add_header Access-Control-Max-Age 86400 always;
}

这里解释下always参数的作用：默认情况下add_header只在响应码为200、201、204、206、301、302、303、304、307、308时才会添加响应头，如果后端返回404、500等错误码，CORS头会丢失，导致前端在错误场景下报跨域错误，加上always可以避免这个问题。

步骤2：location块处理反向代理和OPTIONS请求

在代理后端的location块里添加如下配置，优先处理OPTIONS预检请求，同时隐藏后端返回的CORS头避免冲突：

location /api/ {
    # 优先处理OPTIONS预检请求，直接返回204，不转发到后端
    if ($request_method = 'OPTIONS') {
        return 204;
    }

    # 隐藏后端返回的CORS头，避免和Nginx配置冲突
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    proxy_hide_header Access-Control-Allow-Headers;
    proxy_hide_header Access-Control-Allow-Credentials;

    # 反向代理配置
    proxy_pass http://backend-server: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;
}

步骤3：动态配置允许的Origin，避免安全风险

不要直接使用Access-Control-Allow-Origin: *，这会允许所有域名跨域访问，存在安全隐患。如果前端域名固定，可以直接写死允许的域名：

set $cors_origin "https://your-frontend.com";
if ($http_origin ~* "^https://(your-frontend.com|admin.your-frontend.com)$") {
    set $cors_origin $http_origin;
}

如果前端域名不固定，可以用map指令做动态白名单匹配，具体配置方法可以参考我之前写的Nginx CORS多域名动态匹配：if与map两种方案深度对比与实战选择，里面详细对比了两种方案的优缺点和生产级配置示例。

三、常见场景扩展配置

场景1：跨域请求需要携带Cookie

如果前端请求需要携带Cookie，除了上面的基础配置，还需要注意两点：一是Access-Control-Allow-Credentials必须设为true，二是Access-Control-Allow-Origin不能设为*，必须指定具体的域名。具体配置方法可以参考Nginx CORS与Cookie携带配置教程：解决跨域请求Cookie丢失的完整实战。

场景2：需要处理预检请求的自定义Header

如果前端请求带了自定义Header（比如X-Custom-Token），需要在Access-Control-Allow-Headers里明确添加这个Header，否则预检请求会失败。同时如果需要处理预检请求的缓存，可以调整Access-Control-Max-Age的值，单位秒，比如设为86400就是缓存24小时，减少预检请求的次数。

四、配置后问题排查清单

如果配置完成后还是出现跨域问题，可以按照下面的清单逐一排查，基本能解决99%的问题：

1. 打开浏览器DevTools的Network面板，查看请求的响应头，确认CORS相关头是否正确返回，是否被后端服务覆盖。
2. 检查所有add_header指令是否都加了always参数，避免错误响应时CORS头丢失。
3. 用命令curl -I -X OPTIONS https://your-domain.com/api/test直接测试预检请求，查看响应码是否为204，是否带上了正确的CORS头。
4. 检查location块内是否有add_header指令覆盖了server块的配置，或者是否有proxy_hide_header误隐藏了CORS头。
5. 确认后端服务是否已经关闭了自身的CORS配置，避免和Nginx的配置冲突。

五、相关文章推荐

如果你还需要了解更多Nginx CORS相关的配置技巧，可以参考下面几篇实战文章：

• Nginx CORS跨域配置详解：从原理到实战的完整指南
• Nginx CORS预检请求OPTIONS处理配置：解决跨域预检失败的完整实战
• Nginx CORS与Cookie携带配置教程：解决跨域请求Cookie丢失的完整实战

总结

Nginx反向代理场景下的CORS配置核心要注意三个点：一是避免后端服务的CORS头和Nginx配置冲突，该隐藏的隐藏；二是正确处理OPTIONS预检请求，避免预检失败；三是所有add_header都要加always参数，确保全场景响应头都生效。按照本文的步骤配置，基本可以解决反向代理后的所有跨域失效问题。