1. 为什么非根目录部署会出问题第一次尝试把RuoYi-Vue部署到/admin/路径下时我遇到了刷新页面就404的尴尬情况。这其实是SPA应用在History路由模式下的经典问题当用户直接访问/admin/system/user这样的子路由时Nginx会把这个路径当作真实存在的文件路径去查找而实际上这些路由是由前端Vue Router控制的虚拟路径。核心矛盾点在于静态资源路径错乱打包后的js/css文件默认从根目录加载部署到子目录后找不到资源路由匹配失效Nginx没有把非根路径的请求正确转发给index.htmlAPI请求路径错误前端请求的API地址仍然从根目录发出我曾在测试环境用Hash模式带#的路由临时解决问题但实际项目必须用History模式。后来发现需要同时修改以下四个位置的配置才能完美解决2. 前端环境变量配置在项目根目录的.env.production文件中增加基础路径配置其他环境文件也需要同步修改# 生产环境配置 VUE_APP_BASE_URL /admin/这个变量会影响到三个关键位置静态资源加载路径通过vue.config.js中的publicPath配置路由基础路径在router/index.js中设置base参数请求路径拼接在utils/request.js中修正API请求地址实测发现如果只改其中一两处会出现各种诡异问题。比如我最初漏改了request.js结果登录成功后页面直接白屏控制台报错找不到JS文件。3. Vue项目配置调整3.1 修改vue.config.jsmodule.exports { publicPath: process.env.VUE_APP_BASE_URL, // 关键修改点 devServer: { // 开发环境配置... } }这里有个坑旧版本可能配置的是baseUrl而Vue CLI 3版本需要使用publicPath。我曾经因为用错属性名导致打包后所有静态资源404。3.2 调整路由配置在src/router/index.js中修改Router实例export default new Router({ base: process.env.VUE_APP_BASE_URL, // 新增配置 mode: history, routes: constantRoutes })如果不加这个配置刷新页面时Vue Router会从根路径开始匹配路由导致页面组件加载失败。3.3 修正请求路径在src/utils/request.js中找到所有硬编码的路径改为动态拼接// 修改前 location.href /index // 修改后 location.href process.env.VUE_APP_BASE_URL /index类似修改还需要在src/layout/components/Navbar.vue等包含路径跳转的文件中进行。我曾经因为漏改Navbar.vue导致退出登录后跳转到了404页面。4. Nginx关键配置详解这是整个部署过程中最容易出错的部分先看最终可用的配置模板location /admin/ { alias /home/project/ruoyi-ui/dist/; try_files $uri $uri/ /admin/index.html; index index.html; # 静态资源缓存配置 location ~* \.(js|css|png|jpg)$ { expires 1y; add_header Cache-Control public, immutable; } }4.1 alias与root的区别root会把location路径拼接到指定目录后alias直接映射指定目录不拼接location路径比如# 错误示例会导致路径变成/home/project/ruoyi-ui/dist/admin/ location /admin/ { root /home/project/ruoyi-ui/dist; } # 正确用法 location /admin/ { alias /home/project/ruoyi-ui/dist/; # 注意结尾的/ }4.2 try_files指令解析这个配置是解决404问题的核心try_files $uri $uri/ /admin/index.html;它的执行逻辑是先尝试查找真实存在的文件$uri再尝试查找目录$uri/都找不到时返回index.html交给前端路由处理4.3 常见配置错误路径结尾缺少斜杠alias /home/project/ruoyi-ui/dist; # 错误 alias /home/project/ruoyi-ui/dist/; # 正确try_files顺序错误try_files /admin/index.html $uri $uri/; # 错误location匹配冲突location / { try_files $uri $uri/ /index.html; } location /admin/ { # 这个配置永远不会生效 }5. 完整部署流程检查清单前端构建npm run build:prod检查dist目录是否生成正确静态资源路径是否包含/admin/前缀Nginx配置验证nginx -t systemctl restart nginx问题排查技巧浏览器F12查看Network面板确认资源加载路径检查Nginx错误日志tail -f /var/log/nginx/error.log使用curl测试API接口响应我在实际部署中遇到过静态资源加载失败的问题最后发现是因为Nginx配置中多了个rewrite规则导致路径被改写。建议每次修改配置后都清空浏览器缓存再测试。6. 多应用部署方案当需要在同一域名下部署多个RuoYi应用时比如/admin/和/portal/可以这样配置# 后台管理系统 location /admin/ { alias /home/admin-ui/dist/; try_files $uri $uri/ /admin/index.html; } # 用户门户系统 location /portal/ { alias /home/portal-ui/dist/; try_files $uri $uri/ /portal/index.html; } # API接口转发 location /admin-api/ { proxy_pass http://backend-server; proxy_set_header Host $host; }这种架构下要特别注意每个应用使用独立的环境变量配置API路径需要区分不同前缀静态资源缓存策略要分开设置7. 进阶优化技巧CDN加速配置 修改vue.config.js中的publicPath为CDN地址publicPath: process.env.NODE_ENV production ? https://cdn.example.com/admin/ : process.env.VUE_APP_BASE_URLGzip压缩 在Nginx中添加配置gzip on; gzip_types text/plain application/xml application/javascript;浏览器缓存策略location ~* \.(js|css|png)$ { expires 1y; add_header Cache-Control public, immutable; }安全头设置add_header X-Frame-Options SAMEORIGIN; add_header X-Content-Type-Options nosniff;经过这些优化后我们的管理后台在Chrome Lighthouse测试中性能评分从58提升到了92。特别是在弱网环境下页面加载速度提升了3倍以上。