使用Vue CLI(Vue2)配置相对路径实现任意子文件夹免重编译部署

核心根因 #

你遇到的「静态资源全部加载成功、控制台无报错、但页面无法挂载渲染」的问题，本质是仅配置了打包工具的静态资源相对路径，没有同步适配路由初始化、动态资源加载的路径逻辑。
尤其是路由环节，如果沿用默认的/作为base值，在非根子路径下会出现路由路径和规则不匹配的问题；而hash路由模式下匹配不到规则不会抛出显性错误，最终就表现为应用无任何报错、但始终无法完成挂载流程。

分步骤配置（Vue CLI + Vite 通用） #

1. 修正打包工具的基础路径配置 #

之前用publicPath: ""的写法存在场景兼容问题，空字符串会导致路径拼接跟随当前页面URL动态变化，深层路由下会出现路径错误。统一改为明确的相对路径前缀：

// Vue CLI 项目 vue.config.js
module.exports = {
  publicPath: './', // 明确声明所有静态资源基于当前HTML文件路径加载
  productionSourceMap: false, // 关闭sourcemap避免额外路径依赖
}

// Vite 项目 vite.config.js
export default defineConfig({
  base: './', // 对应Vue CLI的publicPath配置
})

2. 适配路由初始化配置（最关键的挂载失败诱因） #

绝大多数人配完打包配置就忽略了路由的base设置，路由初始化时如果拼接的路径和实际部署子文件夹不匹配，会出现路由规则匹配为空、无报错但页面空白的问题。
针对自由迁移场景，优先选择hash路由模式（不依赖服务器路由重写，换任意子文件夹都能直接跑），不要写死路由base值，改为动态读取当前HTML的部署路径：

// 路由初始化文件 src/router/index.js
import Vue from 'vue'
import VueRouter from 'vue-router'

Vue.use(VueRouter)

const routes = [
  // 你的业务路由规则
]

const router = new VueRouter({
  mode: 'hash',
  // 动态截取当前页面去掉文件名、hash后的路径作为路由base，自动适配任意子文件夹
  base: window.location.pathname.replace(/\/[^\/]*(#.*)?$/, ''),
  routes
})

export default router

注意：如果是Vite+Vue3的项目，路由初始化逻辑和上面完全一致，同样用动态base配置即可。
不推荐在自由迁移场景下使用history路由模式：该模式依赖服务器端的路由重写规则，换子文件夹必须同步修改服务器配置，完全不符合「不重新编译、不修改服务器配置就能随意迁移」的业务需求。

3. 兜底动态懒加载的资源路径 #

配置完基础路径后，异步路由懒加载的chunk文件可能会在路由跳转时出现路径拼接错误，需要在入口文件最顶部（所有业务模块import之前）设置全局的资源加载基路径，避免路径错位：

// Vue2/Vue3 通用入口文件 src/main.js 最顶部
// 动态计算当前HTML所在的目录绝对路径，作为所有动态资源的加载基地址
window.__webpack_public_path__ = window.location.pathname.replace(/\/[^\/]*$/, '/')

常见排查点 #

• 不要在代码中硬写绝对路径的静态资源引用（比如<img src="/static/logo.png">），这类路径不受publicPath配置影响，迁移后必然加载失败，要改为import引入或相对路径引用
• 页面空白且无报错时，优先在控制台手动执行document.getElementById('app')确认能拿到根挂载DOM，再手动触发一次应用挂载流程，排查有没有插件初始化时的静默报错
• 不要把publicPath设为/或者完全写死的绝对路径，会直接失去自由迁移的能力

内容的提问来源于stack exchange，提问作者germi