在Nuxt.js 3项目中如何将HTML字符串标签替换为Vue 3组件？

问题根源 #

使用<Component :is="{template: ...}" />动态渲染模板时，SSR生成的静态HTML与客户端hydration后的DOM不匹配，导致组件短暂显示后被Vue的hydration机制替换，出现闪烁/消失现象。

可行解决方案 #

方案1：占位符替换+客户端挂载组件 #

先在服务端将自定义标签替换为占位符，客户端再把占位符换成真实组件，避免hydration不匹配：

1. 解析富文本，提取组件信息并替换占位符

const parsePollsFromHtml = (html) => {
  const pollRegex = /<custom-poll\s+id="(\d+)"\s*\/>/g
  const polls = []
  let match
  // 提取所有poll的id
  while ((match = pollRegex.exec(html)) !== null) {
    polls.push({ id: match[1] })
  }
  // 替换为带标识的占位符
  const processedHtml = html.replace(pollRegex, '<span class="poll-placeholder" data-id="$1"></span>')
  return { processedHtml, polls }
}

2. 在组件中实现渲染与替换

<template>
  <div ref="htmlWrapper" v-html="processedHtml"></div>
</template>

<script setup>
import Poll from '~/components/Poll.vue'
import { ref, onMounted, onServerPrefetch } from 'vue'

// 模拟API返回的富文本
const rawHtml = '<div><custom-poll id="9" /></div>'
const processedHtml = ref('')
const polls = ref([])
const htmlWrapper = ref(null)

// SSR阶段预解析HTML
onServerPrefetch(() => {
  const result = parsePollsFromHtml(rawHtml)
  processedHtml.value = result.processedHtml
  polls.value = result.polls
  return Promise.resolve()
})

// 客户端挂载Poll组件到占位符位置
onMounted(() => {
  polls.value.forEach(poll => {
    const placeholder = htmlWrapper.value?.querySelector(`.poll-placeholder[data-id="${poll.id}"]`)
    if (placeholder) {
      const app = createApp(Poll, { id: poll.id })
      app.mount(placeholder)
    }
  })
})
</script>

方案2：用HTML解析器生成Vue渲染函数 #

使用htmlparser2解析HTML，直接生成Vue渲染函数，确保SSR和客户端渲染一致：

1. 安装依赖

npm install htmlparser2

2. 编写解析转换函数

import { parseDOM } from 'htmlparser2'
import { h } from 'vue'
import Poll from '~/components/Poll.vue'

const convertHtmlToVueNodes = (html) => {
  const domNodes = parseDOM(html)
  
  const renderNode = (node) => {
    if (node.type === 'tag') {
      // 处理自定义poll标签
      if (node.name === 'custom-poll') {
        return h(Poll, { id: node.attribs.id })
      }
      // 处理普通HTML标签
      return h(node.name, node.attribs, node.children.map(renderNode))
    }
    // 处理文本节点
    if (node.type === 'text') return node.data
    return null
  }

  return domNodes.map(renderNode)
}

3. 在组件中使用

<template>
  <div>
    <component :is="renderContent" />
  </div>
</template>

<script setup>
import { ref, onServerPrefetch } from 'vue'

const rawHtml = '<div><custom-poll id="9" /></div>'
const renderContent = ref(null)

// SSR阶段生成渲染函数
onServerPrefetch(() => {
  renderContent.value = () => convertHtmlToVueNodes(rawHtml)
  return Promise.resolve()
})
</script>

关键说明 #

动态模板<Component :is="{template: ...}" />无法被Nuxt SSR正确预渲染，服务端只会输出空结构，客户端hydration时因为DOM不匹配，Vue会重新渲染并替换原有内容，导致闪烁。上面两种方案都是通过确保SSR和客户端渲染的内容一致，避免hydration冲突来解决问题。

内容的提问来源于stack exchange，提问作者Joker Dark Knight