WordPress插件Vue组件使用v-for报Invalid VNode type: Symbol(Fragment)错误

• 报错的核心原因是插件编译产物中包含了独立的Vue运行时副本，和主题侧挂载的Vue主实例不是同一个实例。Vue3 中Fragment、Teleport 等内置组件对应的Symbol标识是和当前Vue实例绑定的，两个不同副本的Symbol值不相等，渲染时无法识别就会抛出Invalid VNode type: Symbol(Fragment)错误。
• 你用到v-for时触发报错的原因是：Vue3 处理v-for列表时会默认生成Fragment包裹节点，而组件基础渲染时没有多节点场景不需要Fragment，所以只有用到v-for时才会触发问题。
• 组件迁移到主题中不报错的原因是：所有组件都用同一个Vue实例编译运行，不存在多副本冲突。

方案1：将Vue设置为插件的外部依赖（最推荐） #

第一步：主题侧暴露全局Vue实例 #

在主题的入口JS文件中添加如下代码，将Vue挂载到window对象供插件调用：

// 如果你用的是Vue2
import Vue from 'vue'
window.Vue = Vue

// 如果你用的是Vue3
import * as Vue from 'vue'
window.Vue = Vue

第二步：修改插件的Webpack配置 #

在插件的webpack.config.js中添加externals配置，禁止将Vue打包进插件产物，直接复用全局的Vue实例：

module.exports = {
  // 其余原有配置保持不变
  externals: {
    vue: 'Vue'
  }
}

配置完成后重新编译插件，所有import Vue from 'vue'的调用都会自动指向window.Vue，保证和主题用同一个Vue实例。

方案2：插件侧直接使用全局Vue方法 #

如果不想修改Webpack配置，可以直接调整插件的组件写法，所有Vue相关的API都从window.Vue上获取，不要在插件中导入Vue：

// 插件侧组件代码不要导入vue
// 错误写法：import { defineComponent } from 'vue'
// 正确写法：
const { defineComponent } = window.Vue;

export default defineComponent({
  // 原有组件配置保持不变
  name: 'search-bar',
  data() {/* ... */}
})

版本对齐要求 #

无论用哪种方案，都需要保证插件开发依赖的Vue大版本和主题使用的Vue版本完全一致，比如主题用Vue 3.2.45，插件的devDependencies里的vue版本也必须是3.2.x，避免版本差异带来的兼容问题。

修改完成后在插件的组件mounted钩子中添加如下代码，确认共用实例生效：

mounted() {
  // 打印结果为true则说明配置生效
  console.log('是否共用Vue实例:', this.$.appContext.app.version === Vue.version)
}

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