Nuxt3中vue-mathjax-next无法渲染LaTeX公式的问题求助

问题说明 #

在 Nuxt3 项目中使用 vue-mathjax-next 库渲染 LaTeX 公式时，出现服务端与客户端 DOM 不匹配的错误，导致公式无法正常渲染。相关代码及报错信息如下：

组件代码 #

<template>
  <div>
    <textarea v-model="formula"/>
    <vue-mathjax :formula="formula"/>
  </div>
</template>

<script setup lang="ts">
const formula = ref('$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$');
</script>

插件配置（/plugins 目录） #

import VueMathjax from 'vue-mathjax-next';

export default defineNuxtPlugin(({ vueApp }) => {
    vueApp.use(VueMathjax)
})

报错信息 #

• Client vnode: span
• Server rendered DOM:
  at <VueMathjax formula="$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$" >
  at <Test onVnodeUnmounted=fn<onVnodeUnmounted> ref=Ref< undefined > >
  ...（省略后续路由层级信息）

需要渲染的目标 LaTeX 内容：

约分：$\dfrac{7}{10}$
分子分母同乘一个数：$\dfrac{7}{10} \times \dfrac{10}{10}$
合并为单个分数：$\dfrac{7 \times 10}{10 \times 10}$
计算乘积或商：$\dfrac{70}{100}$
将分母为100的分数改写为百分比：$70%$

解决步骤 #

1. 仅在客户端注册插件 #

修改插件配置，确保 vue-mathjax-next 只在客户端环境中注册，避免服务端渲染时出错：

import VueMathjax from 'vue-mathjax-next';

export default defineNuxtPlugin(({ vueApp }) => {
  // 仅在客户端执行注册
  if (process.client) {
    vueApp.use(VueMathjax);
  }
})

2. 使用 <ClientOnly> 包裹组件 #

在模板中用 Nuxt 提供的 <ClientOnly> 标签包裹 vue-mathjax 组件，强制其仅在客户端渲染：

<template>
  <div>
    <textarea v-model="formula"/>
    <ClientOnly>
      <vue-mathjax :formula="formula"/>
    </ClientOnly>
  </div>
</template>

<script setup lang="ts">
const formula = ref('$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$');
</script>

3. 直接定义客户端组件（推荐） #

使用 Nuxt3 的 defineClientComponent 工具，直接在组件中导入并注册客户端专用的 vue-mathjax-next 组件，无需全局注册：

<template>
  <div>
    <textarea v-model="formula"/>
    <VueMathjax :formula="formula"/>
  </div>
</template>

<script setup lang="ts">
// 定义仅在客户端加载的组件
const VueMathjax = defineClientComponent(() => import('vue-mathjax-next'));
const formula = ref('$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$');
</script>

原理说明 #

vue-mathjax-next 依赖浏览器环境中的 MathJax 运行时，服务端渲染时无法生成对应的 DOM 结构，导致客户端 hydration 阶段出现 DOM 不匹配错误。通过上述方法确保组件仅在客户端运行，即可解决该问题。

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