Vue2项目执行vite build遇模板解析错误，求排查解决

问题现象 #

执行vite build时触发Vue模板解析错误，具体报错如下：

1. 错误1：Expected ">" but found "class"，报错位置指向代码片段：

   <template>
        <div class="dashboard container">
             ^
       ...
   </template>
   

2. 错误2：Unexpected "/"，报错位置指向代码片段：

   <template>
        <div>
            <navbar></navbar>
                     ^
        ...
   </template>
   

同时伴随特殊表现：

• 服务器构建完全正常，本地构建失败，但双方npm、node及所有包版本（含全局包）完全一致
• 本地构建偶尔能成功（约每20次执行出现1次）
• 每次构建失败时，报错的目标文件不固定
• vite dev模式始终能正常运行

排查与解决建议 #

1. 强制清空Vite构建缓存

随机报错、偶尔成功的特征大概率是缓存异常导致：

• 执行vite build --force命令强制跳过缓存直接构建
• 手动删除项目根目录下的node_modules/.vite缓存文件夹，再重新执行构建

2. 锁定vite-plugin-vue2兼容版本

Vue2在Vite生态下依赖vite-plugin-vue2，版本不匹配会引发随机解析bug：

• 查看package.json中vite-plugin-vue2版本，建议锁定到稳定分支（如^2.0.0）
• 执行npm install vite-plugin-vue2@latest --save-dev更新插件，同时删除package-lock.json/yarn.lock后重新安装全量依赖

3. 校验自定义组件的注册与命名

错误2指向自定义组件<navbar>，需确认：

• 组件是否完成正确注册（全局注册或局部导入注册）
• 确保组件注册名称与模板中使用的名称完全匹配，Vue2允许模板用kebab-case（<navbar>）对应PascalCase（Navbar）的组件类，但需避免命名混淆
• 检查组件文件是否通过vue-class-component正确装饰并导出组件类

4. 排除本地文件系统资源冲突

本地构建随机失败但服务器正常，可能是本地IO进程干扰：

• 关闭杀毒软件、文件同步工具（如OneDrive、坚果云），避免构建时这些工具读写项目文件引发资源竞争
• 在本地新建干净目录，重新拉取代码、安装依赖后尝试构建，排除原有目录文件损坏问题

5. 确保vue-template-compiler与Vue版本严格一致

Vue2要求vue-template-compiler版本必须和vue主包版本完全相同，否则会出现模板解析异常：

• 查看package.json中vue和vue-template-compiler的版本号，确保两者完全一致（如均为2.6.14）
• 版本不一致时，执行npm install vue-template-compiler@<对应Vue版本号> --save-dev修正

6. 检查Vite配置的模板解析规则

查看vite.config.ts中是否存在冲突的模板解析配置：

• 避免手动修改vite-plugin-vue2的template相关配置，保持默认设置
• 暂时禁用@vitejs/plugin-legacy等可能影响模板解析的插件，测试构建是否恢复正常

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