ruoyi后台执行 `npm run build:stage` 时静态资源路径错误，如何修复？

Question

在 RuoYi 前端（Vue 2 + Vue CLI 3/4）执行 `npm run build:stage` 构建预发布包时，常因 `public` 目录下静态资源（如 favicon.ico、logo.png）路径未按 `publicPath` 正确解析，导致 404。根本原因是：Vue CLI 默认将 `public` 中文件直接拷贝至输出目录根路径，但 `build:stage` 脚本通常配置 `--mode staging`，而 `vue.config.js` 中若 `publicPath` 设为相对路径（如 `'./'`）或未与部署子路径（如 `/ruoyi/`）对齐，浏览器请求资源时会基于当前 URL 错误拼接路径。典型表现：页面可访问，但图标、字体、第三方 JS/CSS 加载失败。修复关键：统一配置 `vue.config.js` 的 `publicPath`（推荐设为 `process.env.NODE_ENV === 'production' ? '/ruoyi/' : '/'`），并确保 Nginx/Apache 静态服务路径与之匹配；同时避免在 HTML 或 JS 中硬编码绝对路径。验证方式：检查生成的 `index.html` 中资源链接是否以 `/ruoyi/` 开头。

Answer 1

```html

一、现象层：预发布环境静态资源 404 的典型表现

执行 npm run build:stage 后，部署至 Nginx 子路径（如 /ruoyi/）时，favicon.ico、logo.png、manifest.json 及内联的第三方字体 CSS（如 fonts/iconfont.woff2）频繁返回 404。浏览器开发者工具 Network 面板显示请求路径为 https://domain.com/favicon.ico（而非 /ruoyi/favicon.ico），页面可渲染但视觉降级严重。

二、机制层：Vue CLI 构建路径解析的双重解耦逻辑

• public 目录行为：Vue CLI 将 public/ 下文件无条件拷贝至 dist/ 根目录（如 dist/favicon.ico），不经过 webpack 编译，也不参与 publicPath 动态重写；
• HTML 引用逻辑：index.html 中硬编码的 <link rel="icon" href="/favicon.ico"> 或 <link href="/css/app.xxx.css"> 由 html-webpack-plugin 注入，其 base 路径完全依赖 vue.config.js.publicPath 配置；
• 运行时路径计算：浏览器基于当前 URL（如 https://domain.com/ruoyi/）解析相对路径 ./favicon.ico → https://domain.com/ruoyi/favicon.ico，但若 HTML 中写死 /favicon.ico，则解析为根路径，与实际部署位置错位。

三、配置层：vue.config.js 的 publicPath 多环境精准控制

在 vue.config.js 中必须采用环境感知式声明：

module.exports = {
  publicPath: process.env.NODE_ENV === 'production' 
    ? '/ruoyi/' 
    : (process.env.VUE_APP_ENV === 'staging' ? '/ruoyi/' : '/')
};

⚠️ 关键约束：不可使用 './' 或空字符串；所有非开发环境（包括 staging）必须与 Nginx location 前缀严格一致。

四、验证层：构建产物与服务端协同校验清单

检查项	预期结果	验证命令
dist/index.html 中 <base href="/ruoyi/">	存在且值正确	grep '<base' dist/index.html
dist/index.html 中资源链接	所有 href/src 以 /ruoyi/ 开头	grep -E 'href|src' dist/index.html | head -5
Nginx 静态服务配置	location /ruoyi/ { alias /path/to/dist/; }	nginx -t && nginx -s reload

五、防御层：杜绝硬编码与构建时注入风险

禁止在以下位置出现绝对路径硬编码：

• public/index.html 中手动修改 <link rel="icon"> 的 href 属性；
• main.js 或组件中通过 document.createElement('link') 动态插入未拼接 process.env.BASE_URL 的资源；
• vue.config.js 中 configureWebpack.plugins 错误覆盖 HtmlWebpackPlugin 的 base 选项。

六、进阶层：RuoYi 特定适配与 CI/CD 自动化保障

RuoYi v4.x 默认使用 VUE_APP_ENV=staging 触发 .env.staging，需确保该文件定义：

VUE_APP_ENV=staging
VUE_APP_BASE_API=/ruoyi/prod-api
NODE_ENV=production

CI 流水线（如 Jenkins/GitLab CI）应在构建后自动执行：

cat dist/index.html | grep -q 'href="/ruoyi/' || (echo "❌ publicPath mismatch!" && exit 1)

七、可视化诊断：构建路径决策流程图

flowchart TD
    A[执行 npm run build:stage] --> B{读取 .env.staging}
    B --> C[process.env.VUE_APP_ENV === 'staging']
    C -->|true| D[publicPath = '/ruoyi/']
    C -->|false| E[publicPath = '/']
    D --> F[html-webpack-plugin 注入 base='/ruoyi/']
    F --> G[所有资源 URL 前缀强制为 /ruoyi/]
    G --> H[Nginx location /ruoyi/ 指向 dist/]
    H --> I[浏览器请求 /ruoyi/favicon.ico ✅]

```