Vue 3 项目宝塔面板部署踩坑记录—为什么你的网页一直返回Nginx欢迎页？

前言第一次部署项目就差前端结果一直返回 Nginx 欢迎页问了好几个 AI 都没给我查到问题所在结果是因为宝塔配置 Nginx 服务时自动给覆盖了默认配置导致完全破坏我的项目运行目录。真的得不吐不快 (╯‵□′)╯ 一、介绍项目环境前后端分离项目前端Vue 3 Vite 8 Vue RouterHistory 模式后端Java SpringBoot 项目部署环境Windows Server 宝塔面板目标通过 Nginx 部署前端静态文件并反向代理后端 API二、构建阶段踩坑踩坑 1环境变量配置很重要.env通用所有环境开发、生产、测试都会加载它。通常用来存放完全公开、所有环境都相同的变量比如VITE_APP_NAME我的项目.env.development开发开发阶段下的环境变量仅在dev或serve模式下加载。会覆盖.env中同名的变量。一般存放假数据或本地服务地址.env.prodution生产生产阶段下的环境变量仅在build或start模式下加载。会覆盖.env中同名的变量。用以存放真实域名和正式配置前端变量必须带前缀在 Vite 中只有以VITE_开头的变量才会被暴露给前端代码如import.meta.env.VITE_XXX。如果不带此前缀使用它只在 Node.js 服务端如vite.config.js中有效前端页面读不到。编译时“硬替换”前端环境变量不是运行时的系统变量而是在npm run build打包时就被静态替换进代码里的。这意味着不能在构建完成后通过修改服务器的.env.production文件来改变前端页面的行为——必须重新打包。注意如果有.env.local或.env.development.local它们的优先级最高通常被.gitignore忽略用于本地机器特有的覆盖比如本地调试接口。踩坑 2生产包中包含 Vue DevTools在vite.config.js中直接注册了vueDevTools()插件导致生产构建也会打包进去。用户可通过AltShiftD快捷键打开调试面板暴露组件树和 API 请求信息。plugins: [ vue(), # 按环境条件引入 ...(mode development ? [vueDevTools()] : []), ]建议直接在生产构建前移除该插件。三、Nginx 配置阶段踩坑踩坑 3SPA History 路由未配置回退Vue Router 使用createWebHistory()时路由路径是真实的 URL如/user、/favourites。用户直接刷新或访问这些路径时Nginx 会去磁盘寻找物理文件找不到则返回 404。添加 nginx 配置解决location / { try_files $uri $uri/ /index.html; }踩坑 4宝塔自动生成的多余配置宝塔新建站点时会自动生成并include了大量与本项目无关的配置自动配置的部分 nginx #proxy-cache location ~ /purge(/.*) { # 缓存清除配置用于手动清除 Nginx 代理缓存的接口没用直接删 proxy_cache_purge cache_one $1$is_args$args; } #proxy include proxy/temp.com/*.conf; # 代理配置完全多余会覆盖或干扰向真实部署的后端资源访问 #PHP-INFO-START include php/00.conf; # PHP 解析配置没装 PHP 环境直接删 #PHP-INFO-END #REWRITE-START include rewrite/temp.com/*.conf; # 伪静态重写规则会与try_files冲突还有可能跳转旧域名 #REWRITE-END #redirect include redirect/temp.com/*.conf; # 重定向配置多余后续要配置HTTPS的 SSL 证书才需要总结可见宝塔生成的配置是针对通用场景的大部分都没用只需要精简到保留必要的配置项。最终精简配置参考server { listen 8081; # 换成合适的运行端口 server_name xx.xx.xx.xx; # 换成真实域名 root C:/wwwroot/xxxx/xxx; # 项目解析根目录 index index.html; try_files $uri $uri/ /index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { # API 反向代理 proxy_pass http://127.0.0.1:8080/api/; # 对应真实后端运行路径 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # 屏蔽敏感文件 location ~ ^/(\.user.ini|\.htaccess|\.git|\.svn|\.project|LICENSE|README.md) { return 404; } }四、部署时最头疼的问题重头戏踩坑 6为何一直显示 Nginx 欢迎页现象部署后访问域名始终显示 Nginx 欢迎页无论怎么修改配置都没用。排查过程步骤控制台命令发现检查端口监听netstat -ano | findstr :8081两个 Nginx 进程在监听 8081 端口PID 6848 和 7992本地 file 协议验证file:///C:/wwwroot/.../index.html也是欢迎页 —— 彻底排除了 Nginx 配置问题检查文件内容notepad index.html文件内容本身就是 Nginx 欢迎页的 HTML根因宝塔面板在创建新站点时会自动向站点根目录写入一个默认的index.html即 Nginx 欢迎页覆盖了上传的 Vue 构建产物。解决直接再次上传覆盖项目解析根目录 dist 重启Nginx服务提供一个通用的排查思路file:// 协议直接从硬盘读取文件完全不经过 Nginx。如果这都显示欢迎页说明文件内容本身就是 Nginx 欢迎页被宝塔覆盖了而不是 Nginx 配置或进程的问题五、实践总结正确部署顺序本地npm run build构建生产包本地检查dist/目录结构确认有index.html和assets/服务器上传dist/到目标目录先上传文件再建站点宝塔新建站点根目录指向已上传的文件夹宝塔修改配置文件精简到最简配置宝塔重启 Nginx验证访问域名测试六、技术要点速查知识点说明createWebHistory()Vue Router 的 History 模式URL 不带#需要服务端配合try_files $uri $uri/ /index.htmlNginx SPA 回退规则找不到文件时返回index.htmlvite-plugin-vue-devtools开发工具插件生产环境必须排除netstat -ano | findstr :端口Windows 查看端口监听和 PIDfile:///协议绕过服务器直接访问本地文件用于区分是 Nginx 问题还是文件问题宝塔默认站点机制创建站点时会自动写入默认index.html建议先上传文件再建站最后吐槽宝塔的“自动化”有时候反而成了坑尤其是对于 静态 项目。希望这篇记录能帮到同样踩坑的朋友少走弯路如果觉得有用点个赞再走呗(ヮ)