Vue3 History 模式部署报错:Unexpected Token 问题排查
在 Vue3 项目中开启 Vue Router 的 History 模式后,进行生产环境打包部署时,偶尔会遇到页面白屏,控制台抛出 Uncaught SyntaxError: Unexpected token 的情况。很多开发者第一反应是检查代码语法,但实际上这往往是构建配置导致的资源路径问题。
为什么会报错?
当 publicPath 配置为相对路径(例如 ./)时,浏览器在解析 HTML 文件中的 <script> 标签引用时,会根据当前 URL 动态计算资源地址。在 History 模式下,如果用户刷新页面或手动输入非根路径 URL,浏览器请求的是该路径对应的 HTML,此时相对路径的资源引用就会指向错误的目录,导致 JS 文件无法加载或加载失败,进而引发语法解析错误。
核心修复方案
最直接有效的方法是将构建工具的 publicPath 强制指定为根路径 /。请打开项目根目录下的 vue.config.js 文件,找到相关配置项进行修改。
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
transpileDependencies: true,
// 关键配置:设置为绝对根路径
publicPath: '/',
lintOnSave: false,
})
修改完成后,记得清除缓存并重新执行 npm run build。这样生成的 HTML 中引用的 JS/CSS 文件都会以绝对路径形式存在,无论用户在哪个子路径下访问,资源都能正确加载。
注意事项
- Vite 项目:如果你使用的是 Vite 构建的新项目,配置项位于
vite.config.js,对应的是base字段,同样建议设为'/'。 - 服务器配置:除了前端配置,还需确保 Nginx 或 Apache 等服务器配置了
try_files $uri /index.html;,否则 History 模式的路由刷新会直接返回 404。 - 多环境区分:如果项目需要部署在不同目录下(如
/app/),则publicPath应设为/app/,但大多数单页应用推荐统一使用/。
按照上述步骤调整后,绝大多数因路径导致的 Unexpected token 错误都能得到解决。


