Vue 3 + Vite 项目构建后为纯静态资源，Nginx 需正确配置 root、location、try_files 支持 history 路由，并启用 gzip 与缓存优化；部署问题多因 base 路径不一致或缺失 try_files 导致。
Vue 3 + Vite 项目构建后是纯静态资源，Nginx 只需正确服务 dist 目录，并处理前端路由（如 Vue Router 的 history 模式）的 fallback，就能稳定托管。关键在配置 location、root、try_files 和 gzip 优化。
构建项目并准备静态文件
Vite 默认构建输出到 dist 目录。执行以下命令生成生产就绪的静态文件：
- 运行 npm run build（或 yarn build / pnpm build）
- 确认 dist/ 下有 index.html、assets/ 子目录及各类 JS/CSS/图片资源
- 确保 vite.config.ts 中 base 配置与部署路径一致（如部署在根路径，保持 base: '/'；若子路径如 /admin/，则设为 base: '/admin/'）
Nginx 核心配置要点
以下是最小可用且健壮的 Nginx server 块示例（假设项目部署在服务器根路径）：
- root 指向构建后的 dist 目录绝对路径，例如 root /var/www/my-vue-app/dist;
- location / 块中使用 try_files $uri $uri/ /index.html; —— 这是支持 Vue Router history 模式的必需项，让所有未匹配静态资源的请求都回退到 index.html，交由前端路由接管
- 添加 gzip on; 及相关指令，压缩文本类资源提升加载速度
- 为静态资源（JS、CSS、字体、图片）设置合理 expires 缓存策略，例如 location ~* \.(js|css|woff2|ttf|svg|png|jpe?g|gif)$ { expires 1y; }
常见问题与应对
部署后可能出现白屏、404 或资源加载失败，多数源于以下原因：
- 白屏 + 控制台报错 “Failed to fetch” 或路由跳转无效 → 检查 Nginx 是否漏掉 try_files，或 Vue Router 的 createWebHistory() 中 base 路径与 Nginx root/base 不一致
- CSS/JS 404 → 查看浏览器 Network 面板请求路径，确认是否因 base 设置错误导致资源地址多了一级前缀（如请求 /app/assets/xxx.js 但实际在 /assets/xxx.js），调整 vite.config.ts 的 base 并重新构建
- 刷新子路由返回 404 → 确保该 location 块覆盖全部路径（不要写成 location /app/ 却没配 try_files），且没有更高优先级的 location 冲突
- 跨域或 API 请求失败 → 注意：Nginx 托管的是前端静态文件，后端 API 需单独配置反向代理（用 proxy_pass），不能依赖前端直接跨域调用
进阶建议
提升生产环境健壮性可补充以下实践：
- 启用 HTTP/2（需 HTTPS）和 SSL/TLS（推荐 Let’s Encrypt）
- 用 include mime.types; 确保正确响应 Content-Type（尤其字体、WebP 图片）
- 添加简单健康检查接口（如 location = /healthz { return 200 'ok'; }）供监控探测
- 日志中开启 $request_time 和 $upstream_response_time（如代理后端时），便于性能分析
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
