Nginx实战笔记：Vite代理迁移到Nginx的完整指南

核心目的 ：通过实战掌握Nginx基本配置，解决前端开发中的代理问题 关键坑点 ：$request_uri的传递是解决404问题的核心！

一、Win下载安装Nginx

2、下载解压至指定文件夹内即可，然后打开当前文件夹

3、开启 PowerShell 自动补全（推荐）

python 复制代码

 # 1. 管理员身份运行 PowerShell
 # 2. 安装 PSReadLine 模块
 Install-Module PSReadLine -Force
 
 # 3. 设置 Tab 自动补全
 Set-PSReadLineKeyHandler -Key Tab -Function Complete

4、验证

yaml 复制代码

 D:\SoftWare\nginx-1.28.0> nginx.exe -v
 nginx version: nginx/1.28.0  # 看到这个才是成功
 
 D:\SoftWare\nginx-1.28.0> .\nginx -v  # "." 表示当前目录
 nginx version: nginx/1.28.0

血泪教训 ：在 Windows 下玩命令行，文件名拼写必须 100% 精确。哪怕你就在 nginx.exe 头顶上，输错一个字母照样不认！

二、最终Nginx配置（逐行解析版）

nginx

ini 复制代码

 # 定义服务器块（每个server相当于一个虚拟主机）
 server {
     # 监听80端口（HTTP默认端口）
     listen       80;
     
     # 服务器名称（本地开发用localhost）
     server_name  localhost;
 
     # 处理根路径请求（所有前端页面和资源）
     location / {
         # 核心指令：转发到Vite开发服务器
         proxy_pass http://localhost:5173; 
         
         # ▼▼▼ 必须的请求头配置 ▼▼▼
         
         # 传递原始域名（防止Vite认错"家"）
         proxy_set_header Host $host;
         
         # 传递客户端真实IP（调试日志需要）
         proxy_set_header X-Real-IP $remote_addr;
         
         # 传递代理路径（记录请求链路）
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         
         # 传递原始协议（HTTP/HTTPS）
         proxy_set_header X-Forwarded-Proto $scheme;
         
         # ★★★ 核心解决404的配置 ★★★
         # 传递浏览器完整请求路径（含参数）
         proxy_set_header X-Original-URI $request_uri;
         
         # ▲▲▲ 以上头信息缺一不可 ▲▲▲
     }
 
     # 处理API请求（所有/review_server开头的路径）
     location /review_server {
         # 转发到后端服务器
         proxy_pass http://172.31.128.176;
         
         # ▼▼▼ 跨域解决方案 ▼▼▼
         
         # 允许所有域名访问（开发环境用*，生产要改）
         add_header 'Access-Control-Allow-Origin' '*' always;
         
         # 允许的HTTP方法
         add_header 'Access-Control-Allow-Methods' 'GET,POST,OPTIONS' always;
         
         # 允许的请求头
         add_header 'Access-Control-Allow-Headers' 'Content-Type,Authorization' always;
         
         # ▲▲▲ 跨域配置结束 ▲▲▲
         
         # ▼▼▼ 超时设置（防请求卡死）▼▼▼
         proxy_connect_timeout 60s;   # 连接超时
         proxy_read_timeout 600s;     # 读取超时
     }
 
     # ▼▼▼ 错误页面配置 ▼▼▼
     error_page   500 502 503 504  /50x.html;
     
     # 精确匹配50x.html
     location = /50x.html {
         root   html;  # 从nginx/html目录提供文件
     }
 }

三、配置核心解析表

配置区块	关键指令	作用	是否可省略
location /	`proxy_pass`	转发到前端服务	❌ 必须
	`X-Original-URI`	传递完整路径(坑点)	❌ 必须
location /review_server	`proxy_pass`	转发到后端API	❌ 必须
	`add_header`	跨域解决方案	✅ 可省(有跨域时必加)
	`proxy_connect_timeout`	防止连接卡死	✅ 可省
error_page	`/50x.html`	错误处理页面	✅ 可省

四、为什么必须用`$request_uri`？

问题重现场景

访问首页正常：http://localhost/ → ✅ 200
访问子路径404：http://localhost/src/main.tsx → ❌ 404
直接访问Vite正常：http://localhost:5173/src/main.tsx → ✅ 200

原因深度解析

⚠️ 为什么其他配置无效？

配置	问题	结果
单纯 `proxy_pass`	Nginx 默认会 "标准化" 路径	`/src/main.tsx` 变成 `/`
`$uri`	不包含查询参数	`main.tsx?import` 变 `main.tsx`
`$document_uri`	解码后的路径	可能破坏特殊字符

🌰 实战案例对比

请求： http://localhost/src/main.tsx?import=react

变量	值	Vite 接收到的信息
`$request_uri`	`/src/main.tsx?import=react`	✅ 完整原始路径
`$uri`	`/src/main.tsx`	❌ 丢失查询参数
`$document_uri`	`/src/main.tsx`	❌ 丢失查询参数
默认不传递	`/`	❌ 完全错误

五、遇到问题的自救指南

高频问题解决方案

问题现象	解决步骤
502 Bad Gateway	1. 确认Vite服务已启动 2. 添加`proxy_connect_timeout 60s;`
404 Not Found	1. 检查`X-Original-URI`是否配置 2. 确认路径大小写正确
CORS 跨域错误	1. 补全`add_header`配置 2. 添加OPTIONS请求处理
静态资源加载失败	1. 检查路径中的特殊字符 2. 添加`rewrite`规则

终极调试技巧

在Vite项目中添加中间件打印请求信息：

javascript 复制代码

 // vite.config.ts
 export default {
   server: {
     middlewareMode: true,
     appType: 'spa',
     fs: {
       strict: false,
     },
     configureServer(server) {
       server.middlewares.use((req, res, next) => {
         console.log('收到请求:', req.url, req.headers);
         next();
       });
     }
   }
 }

五、附录：必备Nginx命令

命令	作用	使用频率
`.\nginx.exe`	启动Nginx	★★★
`.\nginx.exe -s stop`	强制停止	★★
`.\nginx.exe -s quit`	优雅停止	★★
`.\nginx.exe -s reload`	重载配置（改配置后必用）	★★★★★
`.\nginx.exe -t`	测试配置文件语法	★★★★★
`taskkill /f /im nginx.exe`	强制终止所有Nginx进程	★★★

实战箴言：

每次修改nginx.conf后 ：必须 -t 测试 → -s reload 重载

遇到路径问题 ：第一时间检查 $request_uri 是否传递

跨域问题：永远先看Network标签的响应头

文件加载失败：先检查浏览器实际访问的URL

通过这个实战案例，你已成功将Vite代理迁移到Nginx，并攻克了最关键的$request_uri坑点！接下来可以探索Nginx更多高级功能了。