Vue 3执行yarn serve导入外部js文件时构建卡在42%无报错如何解决

触发场景 #

在main.ts中引入本地静态JS文件后执行yarn serve，构建进度停滞无报错，日志如下：

42% building 267/276 modules 9 active /Users/mark/Documents/workspace/testapp/test-web/node_modules/html-entities/lib/surrogate-pairs.js

问题产生原因 #

• 构建工具依赖解析死循环：导入的jquery.min.js属于已压缩完成的IIFE/UMD格式脚本，没有标准ES模块导出声明，webpack的依赖扫描loader会反复解析脚本内的压缩字符，调用html-entities处理特殊字符时陷入长时间运行，无错误日志输出。
• TypeScript校验阻塞：项目默认未开启JS文件导入权限，也没有对应JS文件的类型声明，TS校验进程卡在无类型文件的解析环节，不会抛出明确报错。
• 路径别名解析异常：如果@别名的路径解析规则未覆盖assets目录，构建工具会反复遍历项目目录寻找目标文件，导致构建停滞。

解决方法 #

方案1（最优）：公共脚本走静态引入不走构建流程 #

把所有无需二次打包的外部压缩JS文件放到项目public目录下，在public/index.html中直接引入，完全跳过构建解析环节：

<script src="<%= BASE_URL %>js/jquery.min.js"></script>

如果需要TS识别全局变量，在src/env.d.ts中添加全局声明即可：

declare const $: typeof import('jquery')

方案2：配置构建工具跳过静态JS解析 #

如果一定要在main.ts中导入，按使用的构建工具添加对应配置：

Vue CLI（Webpack）

在vue.config.js中添加配置，用script-loader处理静态JS，跳过依赖解析：

module.exports = {
  configureWebpack: {
    module: {
      rules: [
        {
          test: /\.js$/,
          include: /src\/assets\/js/,
          use: ['script-loader']
        }
      ]
    }
  }
}

安装依赖：yarn add script-loader -D

Vite

在vite.config.ts中配置排除预构建：

export default defineConfig({
  optimizeDeps: {
    exclude: ['src/assets/js/*.js']
  }
})

方案3：修正TypeScript配置 #

在tsconfig.json的compilerOptions中开启JS文件支持：

{
  "compilerOptions": {
    "allowJs": true
  }
}

在src/shims-vue.d.ts中添加通用JS模块声明：

declare module '*.js'

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