Nginx 反向代理配置 React 前端与 Python 后端
网罗开发（小红书、快手、视频号同名）
大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。
图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG
我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。
展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！
文章目录
前言
前后端分离项目里，前端通常是 React 打包后的静态资源，后端是 Python（FastAPI/Flask）提供的 API。生产环境一般用 Nginx 做统一入口：对外只暴露 80/443，静态资源由 Nginx 直接返回，/api 等路径转发到后端进程，这样既能隐藏后端端口、又便于做 HTTPS 和缓存。
本文只讲 Nginx 反向代理的核心配置思路和关键片段，不贴完整可运行 Demo，便于快速接入和排查问题。
整体架构
客户端 → Nginx:80/443 ├── / → 静态资源（React build 目录） └── /api → 反向代理到 Python 后端（如 127.0.0.1:8000） - 前端：
npm run build后得到build（或dist）目录，配置 Nginx 的root指向该目录。 - 后端：用 Gunicorn/Uvicorn 监听本机端口（如 8000），只对本机开放；Nginx 用
proxy_pass把/api转到该端口。
基础 server 与静态资源
在 Nginx 的 conf.d 或 sites-available 下新建一个 server 块，例如：
server { listen 80; server_name your-domain.com; # 前端静态资源 root /var/www/app/frontend/build; index index.html; location / { try_files $uri $uri/ /index.html; } } 要点：
- root：指向 React 打包后的目录，请求
/或/xxx时，Nginx 会先找对应文件，找不到再找目录，最后回退到index.html，这样前端的 React Router 才能正确处理浏览器直接访问或刷新子路径。 - try_files：
$uri表示先找同名文件，$uri/表示找同名目录下的默认页，最后/index.html交给 SPA 自己路由。
反向代理 /api 到 Python 后端
在同一个 server 里增加 location /api：
location /api { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; 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; } 要点：
- proxy_pass：后端实际监听地址，若后端是
http://127.0.0.1:8000，且后端路由是/api/xxx，这里写http://127.0.0.1:8000即可；若后端根路径是/，则前端应请求/api/xxx，Nginx 会把/api/xxx原样转给后端，后端需挂载在/api下（如 FastAPI 的app = FastAPI(prefix="/api")）或做路径重写。 - X-Forwarded-Proto：若前面还有 HTTPS 终结，后端需要知道原始协议时，设为
$scheme，后端可信任该头做跳转或生成 URL。 - Host：后端若按 Host 做虚拟主机或校验，应传原始 Host。
路径是否带 /api 的两种写法
方式一：前端请求 /api/xxx，后端也以 /api 为前缀
- 前端：
axios.get('/api/users') - Nginx：
location /api { proxy_pass http://127.0.0.1:8000; }（注意末尾无斜杠） - 转发到后端的请求路径仍是
/api/users，后端需挂载在/api，例如 FastAPI：app = FastAPI(prefix="/api")
方式二：后端根路径是 /，Nginx 做 strip
- Nginx：
location /api/ { proxy_pass http://127.0.0.1:8000/; }（注意两边都有斜杠） - 请求
/api/users会被转成http://127.0.0.1:8000/users，后端只需挂载/users等路由。
按你们前后端约定选一种即可，关键是 proxy_pass 末尾有没有斜杠、以及后端路由前缀要一致。
超时与 body 大小
若接口有上传或长耗时，可适当增大超时和 body 限制：
location /api { proxy_pass http://127.0.0.1:8000; proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; client_max_body_size 20M; 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; } HTTPS 与 80 跳转
正式环境建议全站 HTTPS。用 Certbot 申请证书后，可保留 80 仅做跳转：
server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; root /var/www/app/frontend/build; index index.html; location / { try_files $uri $uri/ /index.html; } location /api { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } } 常见问题
| 现象 | 可能原因 | 处理思路 |
|---|---|---|
| 刷新子路径 404 | SPA 未回退到 index.html | 检查 try_files 最后是否指向 /index.html |
| 接口 502 | 后端未启动或端口不对 | 确认 Gunicorn/Uvicorn 监听地址与 proxy_pass 一致 |
| 接口 404 | 路径前缀不一致 | 对照前端请求路径、Nginx proxy_pass 末尾斜杠、后端 prefix |
| 上传大文件失败 | body 超限或超时 | 增大 client_max_body_size 与 proxy_*_timeout |
总结
Nginx 反向代理前后端分离项目：静态资源用 root + try_files 指向 React build 目录并回退到 index.html；/api 用 proxy_pass 转到 Python 后端，并设置 Host、X-Real-IP、X-Forwarded-Proto 等头。注意 proxy_pass 末尾斜杠与后端路由前缀一致，按需调整超时与 body 大小，生产环境配合 HTTPS 与 80 跳转即可。
