Vue2项目Webpack HMR热更新TypeScript模块报错排查

该问题是Vue2 + ts-loader场景下的典型HMR增量编译兼容问题：全量构建时webpack会将所有处理过的完整模块上下文传递给ts-loader，因此编译正常；触发热重载时，ts-loader增量编译仅接收变更的单文件片段，无法正确识别vue-loader生成的带查询参数的临时模块路径、.vue模块类型以及路径别名映射，同时自带的类型检查逻辑和vue-loader的SFC拆分逻辑冲突，就会抛出找不到模块、找不到导出成员的错误。

• 补充Vue单文件组件类型声明
  在js_src目录下新建shims-vue.d.ts文件，写入以下内容，让TS识别.vue后缀模块和vue-loader生成的带查询参数的临时模块：

declare module '*.vue' {
  import Vue from 'vue'
  export default Vue
}

declare module '*?vue&type=*' {
  const content: any
  export default content
}

• 修正tsconfig.json配置
  在原有tsconfig.json的compilerOptions同级新增include字段，确保TS能扫描到源码和类型声明文件，同时补充skipLibCheck配置跳过依赖库检查减少冲突：

{
  "compilerOptions": {
    "outDir": "./static/dist",
    "noImplicitAny": false,
    "module": "es2015",
    "target": "es5",
    "allowJs": true,
    "strict": true,
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./js_src/*"]
    },
    "moduleResolution": "node",
    "jsx": "preserve",
    "skipLibCheck": true
  },
  "include": [
    "js_src/**/*.ts",
    "js_src/**/*.tsx",
    "js_src/**/*.vue",
    "js_src/shims-vue.d.ts"
  ]
}

• 调整webpack中ts-loader与模块解析配置
  修改webpack.common.js里的ts-loader规则，开启transpileOnly关闭ts-loader自带的增量类型检查（该逻辑和vue-loader HMR存在上下文冲突），同时调整resolve.extensions顺序，移除会导致错误匹配的通配符，把TS后缀放到更高优先级：

// resolve配置修改为
resolve: {
  alias: {
    vue$: 'vue/dist/vue.esm.js',
    '@': path.resolve(__dirname, 'js_src'),
  },
  extensions: ['.ts', '.tsx', '.js', '.vue', '.json'],
},

// ts-loader规则修改为
{
  test: /\.tsx?$/,
  loader: 'ts-loader',
  exclude: /node_modules/,
  options: {
    appendTsSuffixTo: [/\.vue$/],
    transpileOnly: true,
  }
}

• 可选配置（需要保留类型检查时使用）
  如果需要在开发时保留TS类型检查能力，安装fork-ts-checker-webpack-plugin，通过独立进程运行全量类型检查，不会和HMR逻辑冲突。安装依赖后在webpack.common.js中引入插件，加入plugins数组即可：

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

// plugins数组内新增配置
new ForkTsCheckerWebpackPlugin({
  typescript: {
    extensions: {
      vue: true
    }
  }
})

所有配置修改完成后重启dev server，再触发热重载就不会出现上述TypeScript编译错误。

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