第五十五天

博客一：线上Next.js+FastAPI跨域CORS故障完整复盘（面向开发排障实操）

标题：踩坑实录｜Next.js16 + FastAPI 线上CORS跨域报错，一套Nginx反向代理根治方案

前言

最近在Sealos云平台部署一套前后端分离项目，前端Next.js16+TS，后端Python FastAPI，上线后浏览器直接拦截接口请求，报CORS跨域资源共享错误。从环境变量配置疏漏到后端响应头缺失，一步步定位根因，最终通过Nginx同域反向代理彻底解决，完整记录排障流程与落地配置。

一、项目整体技术栈梳理

前端技术栈

1. Next.js 16（App Router涡轮包）：React全栈SSR框架
​
2. TypeScript：全局类型校验，规避前端类型错误
​
3. Fetch API：原生接口请求工具，项目统一封装HTTP请求

后端技术栈

1. FastAPI（Python）：高性能异步接口服务
​
2. Sealos云平台：容器化部署后端API，线上服务域名sealoshzh.site

网络&部署组件

1. Nginx：服务器反向代理核心，本次解决跨域核心工具
​
2. CORS跨域资源共享：本次故障的问题根源
​
3. SNI：SSL/TLS握手域名配置，Nginx代理HTTPS必备参数 proxy_ssl_server_name on 
​
4. frp内网穿透：开发环境将本地前后端服务暴露公网调试

二、故障现象

前端页面加载完成后，所有Fetch请求后端 sealoshzh.site 接口全部被浏览器拦截，控制台抛出标准CORS跨域报错：

Access to fetch at 'https://sealoshzh.site/api/xxx' from origin 'https://?ɍ端域名' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

三、分层排障全过程

步骤1：排查前端环境变量，找到第一层隐患

项目本地开发依赖 .env.local 文件配置后端API地址，上线部署时运维同步配置文件失误， .env.local 内API地址配置为空。
前端请求工具内置降级逻辑：环境变量为空时自动fallback到代码里硬编码的后端公网地址 https://sealoshzh.site 。
这一步直接导致前端页面（前端域名）直接跨域请求后端独立域名，触发浏览器同源策略校验。

步骤2：定位根本原因——后端FastAPI缺失CORS响应头

顺着报错日志排查后端接口响应报文：

1. FastAPI虽然理论上可以配置 CORSMiddleware 全局跨域中间件，但线上部署时忘记引入该中间件；
​
2. 后端所有接口返回的HTTP响应头，没有携带 Access-Control-Allow-Origin 等CORS放行头部；
浏览器同源策略检测到跨域请求，且服务端未声明允许该前端域名访问，直接拦截请求，接口完全无法调用。

步骤3：两种修复思路对比，选定Nginx反向代理方案

方案A：后端FastAPI新增CORS中间件

在FastAPI全局引入CORSMiddleware，配置允许前端域名、允许所有请求方法、携带Cookie等。
缺陷：

1. 多环境域名需要频繁修改配置，上线、测试、本地开发三套域名维护麻烦；
​
2. 多前端项目接入后端时，需要持续维护允许域名白名单，扩展性差；
​
3. 内网frp调试环境依然会出现跨域问题。

方案B：Nginx同域反向代理（最终落地方案）

核心思路：利用Nginx统一域名转发，实现前后端同域名，从根源规避浏览器CORS校验。

1. 前端主域名统一对外提供访问；
​
2. Nginx配置路由匹配 /api/ 开头的请求，全部反向代理转发至Sealos平台的FastAPI后端服务；
​
3. 前端请求接口时，不再写完整后端公网地址，直接请求同域下 /api/xxx 路径；
​
4. Nginx代理开启SNI配置 proxy_ssl_server_name on ，保障HTTPS握手正常。

优势：

• 彻底消除跨域问题，浏览器不存在跨域请求，无需后端配置任何CORS头；
  ​
• 统一网关层管控接口流量，可在Nginx统一添加限流、缓存、请求日志、SSL证书；
  ​
• 本地frp内网穿透、线上Sealos容器部署环境通用，一套配置多环境复用。

四、落地Nginx核心配置片段

五、修复后前端代码改造

1. 清空硬编码后端域名， .env.local 统一配置相对接口前缀：

2. 封装Fetch请求统一读取环境变量，拼接接口路径，不再请求跨域完整域名；
​
3. 重启Next.js前端服务，重新打包部署。

六、故障总结与避坑规范

1. 环境变量校验规范：前端构建阶段增加环境变量校验，API地址为空直接阻断构建，杜绝fallback硬编码兜底逻辑上线；
​
2. 跨域最优实践：线上生产环境优先使用Nginx反向代理实现同域访问，不依赖后端CORS中间件；开发环境可临时开启后端跨域中间件调试；
​
3. HTTPS代理必开SNI：Nginx反向代理HTTPS外部域名时，必须配置 proxy_ssl_server_name on ，否则会出现SSL握手失败；
​
4. 上线前接口预检：上线前抓包查看接口响应头，确认跨域方案生效，提前拦截CORS类线上故障。

结语

本次故障由前端环境配置疏漏+后端缺失跨域头双重问题叠加导致，短期可以通过后端新增CORS中间件临时修复，但长期网关反向代理同域方案才是稳定可维护的最优解。分享完整排障链路，给使用Next.js+FastAPI前后端分离、Sealos云平台部署的开发者提供排障参考。