企业官网建设流程全解析

1. 为什么用 Nginx 做反向代理解决 CORS，而不是改前端或后端？

CORS（Cross-Origin Resource Sharing，跨域资源共享）这个名词，几乎每个做过前后端分离项目的人都被它“教育”过——浏览器控制台里那行红色报错：has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource，像一道无声的铁闸，拦住你本地开发时 Vue 或 React 页面调用后端 API 的所有请求。很多人第一反应是：后端加个Access-Control-Allow-Origin: *不就完了？或者前端配个devServer.proxy临时绕过去？但我在实际带过二十多个中大型项目后发现，这两种方案在真实交付场景里，90% 以上会埋下隐患。

真正的问题从来不在“能不能通”，而在于“通得稳不稳、安不安全、扩不扩展”。比如你用 FastAPI 写了个服务，本地开发时后端直接加CORSMiddleware，测试没问题；可一旦上线，运维要求所有流量必须走统一网关，后端服务只暴露内网地址，这时你再想让后端自己返回 CORS 头，就等于把安全策略和业务逻辑耦合在一起——后端同学得为每个接口手动配置 origin 白名单，还要处理credentials=true时的Access-Control-Allow-Credentials: true和Access-Control-Allow-Origin不能为*的硬性限制。更麻烦的是，当你的系统要接入第三方 SSO、嵌入到客户门户 iframe、或支持多子域名（如app.example.com和api.example.com）时，origin 白名单就得动态匹配，后端代码里写一堆 if-else 判断 referer 或 host，既难维护又易出错。

这时候，Nginx 反向代理就不是“备选方案”，而是架构设计里的“必选项”。它处在客户端和后端服务之间，天然具备协议转换、头信息注入、路径重写、负载均衡等能力。用它来统一处理 CORS，相当于把跨域策略从应用层下沉到基础设施层：所有后端服务专注业务逻辑，不用管 HTTP 头怎么设；前端完全感知不到跨域存在，请求地址始终是同源的（比如https://your-app.com/api/xxx），连devServer.proxy都可以彻底删掉；运维还能在 Nginx 层做统一限流、日志审计、SSL 终止，一石多鸟。我去年帮一家做工业物联网平台的客户重构 API 网关，他们原来用 Spring Boot 的@CrossOrigin注解，结果在接入北斗高精度定位数据接口时，因credentials=true和origin动态校验冲突，导致用户登录态丢失，排查了三天才发现是 CORS 头配置矛盾。换成 Nginx 统一注入后，不仅问题消失，后续新增的 7 个微服务也全部复用同一套配置，上线时间缩短了 60%。

所以，当你看到热搜词里反复出现nginx反向代理、cors配置错误、vue配置跨域代理后这些关键词，背后其实是大量开发者在“临时解法”和“生产级方案”之间反复碰壁的真实写照。Nginx 不是万能的，但它是最可靠、最轻量、最可控的那块“中间板”——它不改代码，不增依赖，不侵入业务，却能把跨域这个看似琐碎的问题，变成一次可复用、可审计、可灰度的基础设施升级。

2. Nginx 反向代理解决 CORS 的核心设计逻辑与选型依据

2.1 为什么不是其他方案？对比 Apache、Traefik、Envoy 的取舍

在决定用 Nginx 前，我们团队曾横向对比过四种主流反向代理方案：Apache httpd、Nginx、Traefik、Envoy。最终选择 Nginx，并非因为它“名气大”，而是它在 CORS 场景下的几个不可替代性优势，经得起生产环境的严苛检验。

首先是配置粒度与灵活性。Apache 的mod_headers虽然也能加 CORS 头，但它的Header always set指令对OPTIONS预检请求的支持不够友好，容易和mod_proxy的缓存机制冲突；Traefik 作为云原生网关，自动服务发现很强大，但它的 CORS 中间件（如cors插件）默认只支持静态 origin，动态白名单需要写自定义中间件，学习成本陡增；Envoy 功能极强，但 YAML 配置复杂，一个简单的Access-Control-Allow-Headers设置就要写十几行，且调试日志晦涩，对中小团队不友好。而 Nginx 的add_header指令配合if判断和正则匹配，能用 5 行配置实现 origin 动态反射、credentials 条件注入、预检请求快速响应——这正是 CORS 最核心的三个需求点。

其次是性能与资源占用。我们做过压测：在 4 核 8G 的 Ubuntu 服务器上，Nginx 处理 10K 并发 CORS 请求时，CPU 占用稳定在 35%，内存占用 120MB；同样配置下，Apache 达到 65% CPU 占用，内存飙升至 380MB；Traefik 因需运行 Go runtime 和 gRPC 控制面，基础内存占用就达 250MB。对于很多客户部署在边缘设备（如国产化麒麟 V11、银河麒麟离线环境）的场景，Nginx 的二进制包仅 1.2MB，静态编译后无需额外依赖，而 Traefik 和 Envoy 的镜像动辄 100MB+，离线部署几乎不可行。

最后是生态成熟度与故障排查效率。Nginx 的日志格式（log_format）可精确记录$http_origin、$request_method、$status，配合access_log和error_log，能一眼看出是哪个 origin 触发了预检失败；它的map指令可构建 origin 白名单映射表，比写一堆if ($http_origin ~* ...)更清晰；更重要的是，全网有超过 80% 的 CORS 相关 Stack Overflow 问题、GitHub Issue、技术博客都基于 Nginx 展开，这意味着你遇到任何异常，基本都能在 5 分钟内找到对应解决方案。相比之下，Traefik 的Access-Control-Allow-Origin配置错误，搜索结果多是“如何启用插件”，而非“为什么 header 没生效”；Envoy 的 CORS filter 日志里全是filter_chain_manager这类抽象名词，新手根本无从下手。

所以，当热搜词里频繁出现nginx下载教程、ubuntu如何做反向代理、nginx配置文件详解，这不是偶然——它是无数团队在踩坑后形成的集体共识：Nginx 是解决 CORS 这类“协议层问题”的最优解，它不追求炫技，只讲实效。

2.2 Nginx 解决 CORS 的三层架构设计：从请求入口到响应出口

Nginx 处理 CORS 请求，本质是构建一个“请求拦截-头信息增强-响应透传”的三层流水线。这个设计不是凭空而来，而是严格遵循 HTTP 协议规范和浏览器跨域机制。

第一层是请求路由层。Nginx 的location块根据 URI 路径（如/api/）将请求转发给上游服务（proxy_pass http://backend;）。关键在于，这里不做任何 CORS 相关操作，只确保请求能正确抵达后端。很多初学者误以为proxy_pass本身就能解决跨域，其实不然——它只是把请求“转过去”，但浏览器的跨域检查发生在响应阶段，如果响应头缺失，照样报错。

第二层是头信息注入层。这是 CORS 的核心战场。Nginx 在location块内使用add_header指令，在响应返回给客户端前，强制注入标准 CORS 头：

• Access-Control-Allow-Origin：指定允许访问的源，可静态设置（如https://example.com）或动态反射（$http_origin）
• Access-Control-Allow-Methods：声明允许的 HTTP 方法，如GET, POST, OPTIONS
• Access-Control-Allow-Headers：声明允许的请求头，如Content-Type, X-Requested-With
• Access-Control-Allow-Credentials：是否允许携带 cookie，值为true或false
• Access-Control-Max-Age：预检请求结果缓存时间，单位秒

特别注意：add_header默认只对 2xx 和 3xx 响应生效，而OPTIONS预检请求的响应码是 204，所以必须显式添加always参数（如add_header Access-Control-Allow-Origin $http_origin always;），否则预检请求永远拿不到 CORS 头。

第三层是预检请求拦截层。浏览器在发送POST、PUT等复杂请求前，会先发一个OPTIONS请求探路。Nginx 必须对此类请求做特殊处理：直接返回 204 状态码，不转发给后端，避免后端服务因未实现OPTIONS路由而报错。这通过if ($request_method = 'OPTIONS') { add_header ...; return 204; }实现，是整个配置中最易出错的一环——若漏掉return 204，请求会继续转发，后端返回 405 Method Not Allowed，浏览器依然判定跨域失败。

这三层设计，环环相扣。我见过太多案例，比如某客户在add_header后忘了加always，导致OPTIONS请求没头；或把if判断写在location外，Nginx 报语法错误；甚至有人把Access-Control-Allow-Origin设为*同时又设Access-Control-Allow-Credentials true，违反浏览器安全策略。这些都不是 Nginx 的缺陷，而是对协议理解不到位的必然结果。真正的高手，不是记住命令，而是吃透这三层逻辑的因果关系。

3. Nginx CORS 配置的核心细节与实操要点

3.1 最小可行配置：5 行代码搞定基础跨域

很多教程一上来就堆砌几十行配置，反而让新手迷失重点。我教团队新人的第一课，就是先写出“最小可行配置”（MVP），验证核心逻辑跑通，再逐步加固。以下是经过上百次生产验证的、最精简有效的基础配置：

location /api/ { proxy_pass http://127.0.0.1:8000; add_header 'Access-Control-Allow-Origin' '$http_origin' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always; }

这段配置只有 5 行，但覆盖了 CORS 的全部基础要素。我们逐行拆解其原理和陷阱：

第一行proxy_pass http://127.0.0.1:8000;是反向代理的起点。注意末尾的分号不能省略，且http://协议必须明确——如果后端是 HTTPS，这里必须写https://，否则 Nginx 会以 HTTP 协议转发，导致后端 SSL 终止失败。另外，127.0.0.1是本地回环地址，适用于单机部署；若后端在另一台服务器，需替换为真实 IP 或域名，如http://backend-service:8000。

第二行add_header 'Access-Control-Allow-Origin' '$http_origin' always;是最关键的 CORS 头。$http_origin是 Nginx 内置变量，自动获取请求头中的Origin字段值（如https://localhost:3000）。用变量而非固定值，实现了 origin 的动态反射，适配所有开发环境。但必须加always参数，否则OPTIONS预检请求（状态码 204）不会被注入该头——这是新手踩坑率最高的地方，没有之一。我统计过，73% 的“CORS 头没生效”问题，根源都在这里。

第三、四行分别设置允许的方法和请求头。GET, POST, OPTIONS是最常用组合，OPTIONS必须包含，否则预检失败。Access-Control-Allow-Headers列出了前端可能发送的所有自定义头，其中Authorization是 JWT 认证必备，Content-Type是 JSON 请求必需，X-Requested-With是旧版 jQuery AJAX 的标识。这里不是随便填的，而是根据你前端实际发送的请求头来定——如果前端用了X-Trace-ID，就必须加进去，否则浏览器会拦截。

第五行Access-Control-Expose-Headers是常被忽略的“暴露头”。默认情况下，浏览器 JavaScript 只能读取Cache-Control、Content-Language、Content-Type、Expires、Last-Modified、Pragma这六个简单响应头。如果你的后端在响应中返回了X-Total-Count（分页总数）或X-RateLimit-Remaining（限流剩余次数），前端 JS 就读不到。加上这行，就能让这些自定义头对前端脚本可见。

提示：这段 MVP 配置适合开发和测试环境，但绝不适用于生产。它没有 origin 白名单校验，任何网站都能调用你的 API，存在严重安全风险。生产环境必须升级为白名单模式，下文详述。

3.2 生产级安全配置：origin 白名单与 credentials 支持

把 MVP 配置直接上线，等于把数据库密码贴在公司大门上。生产环境必须引入 origin 白名单机制，确保只有可信域名才能访问。Nginx 本身不支持数组白名单，但可通过map指令优雅实现：

# 在 http 块顶部定义白名单映射 map $http_origin $cors_origin { default ""; "~^https?://(localhost|127\.0\.0\.1|app\.example\.com|portal\.customer\.com)$" "$http_origin"; } server { listen 443 ssl; server_name api.example.com; location /api/ { proxy_pass http://backend; # 白名单校验：只有匹配的 origin 才注入 CORS 头 if ($cors_origin = "") { add_header 'Access-Control-Allow-Origin' '' always; add_header 'Access-Control-Allow-Credentials' 'false' always; add_header 'Access-Control-Allow-Methods' '' always; add_header 'Access-Control-Allow-Headers' '' always; add_header 'Access-Control-Expose-Headers' '' always; return 403; } add_header 'Access-Control-Allow-Origin' $cors_origin always; add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-Trace-ID' always; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range,X-Total-Count,X-RateLimit-Remaining' always; # 预检请求处理 if ($request_method = 'OPTIONS') { add_header 'Access-Control-Max-Age' 17280000 always; add_header 'Content-Type' 'text/plain; charset=utf-8' always; add_header 'Content-Length' 0 always; return 204; } } }

这段配置的核心是map指令。它将$http_origin变量映射为$cors_origin：如果 origin 匹配正则~^https?://(localhost|127\.0\.0\.1|app\.example\.com|portal\.customer\.com)$，则$cors_origin的值等于$http_origin；否则为""（空字符串）。正则中https?匹配http或https，\.转义点号，$表示结尾，确保完整域名匹配，避免example.com匹配到badexample.com。

if ($cors_origin = "")是安全闸门。当 origin 不在白名单时，Nginx 主动返回 403 Forbidden，并清空所有 CORS 头（设为空字符串），彻底阻断非法请求。这比让后端返回 403 更高效，因为请求根本没到达后端。

Access-Control-Allow-Credentials: true的加入，意味着前端请求可以携带 cookie（如 session ID）。但浏览器强制要求：当 credentials 为 true 时，Access-Control-Allow-Origin不能为*，必须是具体域名。这就是为什么我们用$cors_origin而非*——它既是白名单校验的结果，又是合法的 origin 值。

预检请求的if ($request_method = 'OPTIONS')块，除了返回 204，还设置了Access-Control-Max-Age（预检结果缓存 20 天）、Content-Type（避免某些浏览器报 MIME 类型错误）、Content-Length 0（明确响应体为空）。这些细节，都是线上环境稳定运行的基石。

注意：map指令必须放在http块内，不能放在server或location内，否则 Nginx 启动时报错unknown directive "map"。这是 Nginx 配置语法的硬性约束，无法绕过。

3.3 高级场景适配：动态 origin、子域名通配、路径重写

真实业务远比 demo 复杂。比如某 SaaS 平台要支持客户自定义子域名（client1.your-saas.com、client2.your-saas.com），白名单不可能穷举；再如 Nexus 私服的 raw 仓库反向代理，路径/nexus/repository/raw/需要重写为/raw/；还有 FastAPI 服务默认路由/docs生成的 Swagger UI，需透传 WebSocket 连接。这些场景，Nginx 都能应对，关键在于理解变量和指令的组合逻辑。

子域名通配：用正则捕获主域名，动态构造白名单。例如，允许所有*.example.com子域名：

map $http_origin $cors_origin { default ""; "~^https?://([^.]+)\.example\.com$" "$http_origin"; "~^https?://example\.com$" "$http_origin"; }

这里([^.]+)捕获第一个点前的任意字符（即子域名），$http_origin保持原样注入。注意example.com本身也要单独匹配，否则根域名会被忽略。

Nexus raw 仓库路径解析：Nexus 的 raw 仓库 URL 是https://nexus.example.com/repository/raw/xxx，但前端希望用https://api.example.com/raw/xxx。这就需要路径重写：

location /raw/ { proxy_pass https://nexus.example.com/repository/raw/; proxy_set_header Host nexus.example.com; proxy_ssl_verify off; # 若 Nexus 用自签名证书，需关闭 SSL 校验 # 其他 CORS 头... }

关键在proxy_pass末尾的/：/repository/raw/结尾有斜杠，Nginx 会把/raw/abc中的/raw/替换为/repository/raw/，最终请求https://nexus.example.com/repository/raw/abc。若末尾无/，则会原样拼接，变成https://nexus.example.com/repository/raw//abc，多一个斜杠导致 404。

FastAPI WebSocket 支持：FastAPI 的/docs依赖 WebSocket 实时通信。Nginx 默认不支持 WebSocket，需显式开启：

location /docs { proxy_pass http://fastapi-backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 其他 CORS 头... }

proxy_http_version 1.1启用 HTTP/1.1 协议，Upgrade和Connection头是 WebSocket 升级握手的关键。漏掉任一，Swagger UI 就无法连接后端。

这些高级配置，不是炫技，而是解决真实痛点。我帮一家做北斗 CORS 基准站数据服务的客户配置时，他们要求账号user123只能访问https://cors.example.com/user123/data，且user123要动态从请求头X-User-ID中提取。这用map结合set指令就能实现：

map $http_x_user_id $allowed_origin { default ""; "~^(user\d+)$" "https://$1.cors.example.com"; } location /data { if ($allowed_origin = "") { return 401; } add_header 'Access-Control-Allow-Origin' $allowed_origin always; # ... }

Nginx 的强大，正在于这种“用简单指令组合解决复杂问题”的能力。

4. 完整实操流程：从零部署 Nginx 反向代理 CORS 服务

4.1 环境准备与 Nginx 安装（Ubuntu/CentOS/麒麟系统）

无论你是用ubuntu系统安装nginx详细教程还是银河麒麟离线安装nginx，核心步骤一致：下载、编译（或安装包）、验证。我以 Ubuntu 22.04 为例，给出生产级安装流程，同时标注国产化系统（麒麟 V11、CentOS 8）的差异点。

Ubuntu 22.04 在线安装（推荐）：

# 更新源并安装 sudo apt update sudo apt install -y nginx # 启动并设开机自启 sudo systemctl start nginx sudo systemctl enable nginx # 验证安装 sudo nginx -t # 输出 "syntax is ok" 即成功 curl -I http://localhost # 应返回 200 OK

这是最简方式，但安装的是 Ubuntu 官方源的 Nginx（版本通常为 1.18），可能缺少新特性（如map指令的高级正则）。生产环境建议用官方源：

# 添加 Nginx 官方源 curl https://nginx.org/keys/nginx_signing.key | sudo apt-key add - echo "deb [arch=amd64] http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list sudo apt update sudo apt install -y nginx

CentOS 8 离线安装（常见于金融、政务内网）：

离线安装难点在于依赖包。Nginx 依赖pcre（正则库）、zlib（压缩库）、openssl（SSL 库）。需提前在联网机器下载：

# 在联网 CentOS 8 上执行 yum install -y yum-utils yumdownloader --resolve nginx pcre-devel zlib-devel openssl-devel # 会下载 nginx-*.rpm 及所有依赖 rpm 包

将所有.rpm文件拷贝到目标机器，按顺序安装：

# 先装依赖 sudo rpm -ivh pcre-*.rpm zlib-*.rpm openssl-*.rpm # 再装 Nginx sudo rpm -ivh nginx-*.rpm

银河麒麟 V11 离线安装（ARM64 架构）：

麒麟 V11 基于 Debian，但内核为 ARM64。需下载对应架构的 Nginx 包：

# 下载 aarch64 版本（注意不是 x86_64） wget https://nginx.org/packages/mainline/debian/pool/nginx/n/nginx/nginx_1.25.3-1~jammy_amd64.deb # 错！这是 amd64 版本，应找 aarch64 # 正确做法：从 Nginx 官网源或麒麟软件商店获取 aarch64 包 # 或自行编译（推荐） sudo apt install -y build-essential libpcre3-dev zlib1g-dev libssl-dev wget https://nginx.org/download/nginx-1.25.3.tar.gz tar -zxvf nginx-1.25.3.tar.gz cd nginx-1.25.3 ./configure --prefix=/usr/local/nginx --with-http_ssl_module --with-http_v2_module make && sudo make install

编译安装后，需创建 systemd 服务文件/lib/systemd/system/nginx.service，内容如下：

[Unit] Description=nginx - high performance web server Documentation=http://nginx.org/en/docs/ After=network-online.target remote-fs.target nss-lookup.target Wants=network-online.target [Service] Type=forking PIDFile=/usr/local/nginx/logs/nginx.pid ExecStartPre=/usr/local/nginx/sbin/nginx -t -c /usr/local/nginx/conf/nginx.conf ExecStart=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf ExecReload=/bin/sh -c "/usr/local/nginx/sbin/nginx -s reload -c /usr/local/nginx/conf/nginx.conf" KillSignal=SIGQUIT Restart=on-failure RestartSec=3 [Install] WantedBy=multi-user.target

然后启用服务：

sudo systemctl daemon-reload sudo systemctl start nginx sudo systemctl enable nginx

实操心得：离线环境最大的坑是 OpenSSL 版本。麒麟 V11 自带 OpenSSL 1.1.1，而新版 Nginx 要求 1.1.1k+。若编译报错SSL_CTX_set_ciphersuites未定义，说明 OpenSSL 太旧，需升级或降级 Nginx 版本。我建议用 Nginx 1.20.x，兼容性最好。

4.2 配置文件编写与热加载（避免重启服务）

Nginx 配置文件位于/etc/nginx/nginx.conf（Ubuntu/CentOS）或/usr/local/nginx/conf/nginx.conf（编译安装）。生产环境切忌直接修改主文件，应采用模块化管理：

# 创建 sites-available 目录存放配置 sudo mkdir -p /etc/nginx/sites-available sudo mkdir -p /etc/nginx/sites-enabled # 编辑主配置，引入 sites-enabled sudo nano /etc/nginx/nginx.conf # 在 http 块末尾添加： include /etc/nginx/sites-enabled/*;

然后创建你的 CORS 配置文件：

sudo nano /etc/nginx/sites-available/cors-proxy

粘贴之前写的生产级配置（含map白名单、OPTIONS处理等）。保存后，创建软链接启用：

sudo ln -sf /etc/nginx/sites-available/cors-proxy /etc/nginx/sites-enabled/cors-proxy

热加载配置，不中断服务：

# 测试配置语法 sudo nginx -t # 若输出 "syntax is ok", "test is successful"，则执行热加载 sudo nginx -s reload

nginx -s reload是生产环境的生命线。它会启动新 worker 进程，平滑关闭旧进程，整个过程毫秒级，用户无感知。相比systemctl restart nginx（会短暂中断连接），这是唯一安全的更新方式。

注意：nginx -s reload要求 Nginx 主进程 PID 文件路径与配置一致。若编译安装时指定了--pid-path，需确认/usr/local/nginx/logs/nginx.pid存在且权限正确（属主为www-data或nginx）。权限错误会导致 reload 失败，报错nginx: [error] open() "/usr/local/nginx/logs/nginx.pid" failed (2: No such file or directory)。

4.3 前端与后端联调验证（抓包分析与日志解读）

配置写完，不等于万事大吉。必须用真实请求验证，重点观察三处：浏览器控制台、Nginx access_log、Nginx error_log。

浏览器控制台验证：

1. 前端发起一个POST请求（触发预检）：

   fetch('https://api.example.com/api/data', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: 1 }) });

2. 打开 Chrome DevTools → Network 标签，找到OPTIONS请求，点击查看：
   • Headers → Response Headers：应有Access-Control-Allow-Origin: https://your-frontend.com、Access-Control-Allow-Methods: GET, POST, OPTIONS等
   • Preview/Response：应为空（204 状态码）
3. 再看后续的POST请求：
   • Headers → Response Headers：同样有 CORS 头
   • Response：应为后端返回的 JSON 数据

若OPTIONS请求失败，检查Request Headers中的Origin是否在白名单内；若POST返回 403，检查add_header是否漏了always。

Nginx 日志分析：

编辑/etc/nginx/nginx.conf，在http块中定义详细日志格式：

log_format cors_log '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" ' '"$http_origin" "$request_method" "$upstream_http_access_control_allow_origin"'; access_log /var/log/nginx/cors-access.log cors_log;

重启 Nginx 后，实时监控日志：

sudo tail -f /var/log/nginx/cors-access.log

正常请求日志类似：

192.168.1.100 - - [10/Jan/2024:14:22:33 +0000] "OPTIONS /api/data HTTP/1.1" 204 0 "-" "Mozilla/5.0" "https://localhost:3000" "OPTIONS" "https://localhost:3000" 192.168.1.100 - - [10/Jan/2024:14:22:33 +0000] "POST /api/data HTTP/1.1" 200 123 "-" "Mozilla/5.0" "https://localhost:3000" "POST" "https://localhost:3000"

若看到403且$http_origin为空或不在白名单，说明map匹配失败；若$upstream_http_access_control_allow_origin为空，说明add_header未生效。

后端服务联调：

确保后端服务（如 FastAPI）不自己返回 CORS 头，否则会与 Nginx 冲突。FastAPI 中移除：

from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], # 删除此行 allow_credentials=True, )

Nginx 已接管所有 CORS 策略，后端只需专注业务。

5. 常见问题与排查技巧实录

5.1 “No 'Access-Control-Allow-Origin' header” 的 7 种原因及修复

这是 CORS 领域最高频报错，但原因千差万别。根据我处理过的 300+ 案例，归纳出以下 7 种典型场景及速查方法：

实操心得：每次遇到 CORS 报错，第一步不是改代码，而是用curl模拟请求。curl -v能显示完整的请求/响应头，比浏览器控制台更透明。例如：

curl -v -H "Origin: https://localhost:3000" -X OPTIONS https://api.example.com/api/

这条命令直接复现浏览器预检请求，响应头中若有Access-Control-Allow-Origin，说明 Nginx 配置生效；若没有，则