Vue2迁移Vue3报错isBuiltInDirective is not a function

问题现象 #

• 构建阶段无编译错误，但输出多条导出缺失警告：@vue/runtime-core、@vue/runtime-dom引用的normalizeProps、isBuiltInDirective、includeBooleanAttr等API，无法从@vue/shared包找到对应导出
• 应用启动后控制台抛出运行时错误：Uncaught TypeError: isBuiltInDirective is not a function，错误触发位置为InstallOGComponents文件中注册PrimeVue指令的代码段：

import PTooltip from 'primevue/tooltip';
app.directive('tooltip', PTooltip);

• 手动核查已安装的@vue/shared包导出列表，确认上述警告提及的缺失方法确实不存在，初步怀疑问题与Webpack配置有关。

根因判断 #

该问题核心是多版本Vue相关依赖冲突，而非Webpack语法配置错误：
Vue3生态下@vue/runtime-core、@vue/runtime-dom、@vue/shared三个包必须版本完全一致，跨版本时会出现高版本runtime包引用低版本shared包不存在的内部API的情况。你当前项目里大概率同时存在两个及以上版本的Vue相关依赖：比如主依赖安装的是高版本Vue，但第三方依赖（最常见是版本不匹配的PrimeVue）引入了低版本@vue/shared，或者Webpack解析依赖时优先命中了错误版本的@vue/shared。
其中isBuiltInDirective这个API是Vue3.3版本才从runtime-dom迁移到@vue/shared导出的，只要出现runtime包是3.3+、shared包是3.2及以下的版本错配，就会100%触发你遇到的报错。

排查步骤 #

1. 先查询本地依赖树的Vue相关包版本分布，执行对应包管理器命令：

   # npm用户执行
   npm ls @vue/shared vue @vue/runtime-core @vue/runtime-dom
   # yarn用户执行
   yarn list --pattern "@vue/shared|vue|@vue/runtime-core|@vue/runtime-dom"
   # pnpm用户执行
   pnpm ls @vue/shared vue @vue/runtime-core @vue/runtime-dom
   

   观察输出结果，如果存在多个版本号的上述包，直接定位到引入错误版本的依赖节点即可。
2. 核查PrimeVue版本适配性：3.10.0以下版本的PrimeVue未做Vue3.3+兼容处理，会直接触发该报错。
3. 核查Webpack的resolve.alias配置：多数Vue2迁Vue3的项目会手动给vue配置别名指向构建版本，但如果漏了@vue/*相关包的统一版本指向，就会出现子包解析到不同版本的问题。

解决方案 #

按优先级从上到下验证即可：

1. 对齐所有Vue相关包版本
   先统一所有Vue相关依赖版本，同时升级PrimeVue到适配版本：

   npm install vue@latest @vue/compiler-sfc@latest primevue@^3.12.0
   

   安装完成后删除node_modules目录和对应锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装，再跑上述依赖树检查命令，确认所有@vue/*包版本完全一致。
2. 配置Webpack强制解析规则，彻底规避多版本共存
   在webpack.config.js的resolve配置中增加别名和模块查找优先级规则，强制所有Vue相关依赖都解析到项目根目录下node_modules内的版本：

   const path = require('path');
   module.exports = {
     // 其余原有配置保持不变
     resolve: {
       alias: {
         // 保留原有vue别名配置
         vue: path.resolve(__dirname, 'node_modules/vue/dist/vue.esm-bundler.js'),
         // 新增@vue子包强制解析规则
         '@vue/shared': path.resolve(__dirname, 'node_modules/@vue/shared'),
         '@vue/runtime-core': path.resolve(__dirname, 'node_modules/@vue/runtime-core'),
         '@vue/runtime-dom': path.resolve(__dirname, 'node_modules/@vue/runtime-dom'),
         '@vue/compiler-dom': path.resolve(__dirname, 'node_modules/@vue/compiler-dom')
       },
       // 配置依赖查找优先级，优先读取项目根目录下的node_modules
       modules: [path.resolve(__dirname, 'node_modules'), 'node_modules']
     }
   }
   

3. pnpm用户额外配置版本覆盖规则
   如果使用pnpm作为包管理器，在package.json中增加如下配置，强制所有依赖引用的Vue相关包使用统一版本：

   {
     "pnpm": {
       "overrides": {
         "@vue/shared": "$@vue/shared",
         "vue": "$vue"
       }
     }
   }
   

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