本文详解在 Nuxt 3 项目中使用 vue-mathjax-next 渲染 LaTeX 数学公式的方法，重点解决因 MathJax 运行时脚本未加载导致的客户端与服务端渲染不一致（如空 span、SSR 内容丢失）问题，并提供基于 useHead 的现代、推荐实践。
本文详解在 nuxt 3 项目中使用 `vue-mathjax-next` 渲染 latex 数学公式的方法，重点解决因 mathjax 运行时脚本未加载导致的客户端与服务端渲染不一致（如空 span、ssr 内容丢失）问题，并提供基于 `usehead` 的现代、推荐实践。
在 Nuxt 3 中直接使用 vue-mathjax-next 组件却无法渲染 LaTeX 公式，根本原因在于：该组件仅提供 Vue 封装逻辑，不自动加载 MathJax 核心库。Nuxt 3 默认启用服务端渲染（SSR），而 MathJax 是纯客户端 JavaScript 库，必须在浏览器环境动态初始化。若未显式引入 MathJax 脚本，组件将无法找到 MathJax.Hub 或 MathJax.typeset() 等 API，导致渲染失败，并出现类似 占位或服务端输出 的警告。
✅ 正确做法是：通过 useHead 在页面/布局级按需注入 MathJax CDN 脚本（推荐），而非过时的 <script> 标签（已自 v3.0.0-rc.14 起废弃）。</script>
以下为完整可运行方案：
1. 安装并注册插件
确保已安装 vue-mathjax-next：
npm install vue-mathjax-next
在 plugins/mathjax.client.ts 中注册（注意 .client.ts 后缀，确保仅在客户端执行）：
import { defineNuxtPlugin } from '#app'
import VueMathjax from 'vue-mathjax-next'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(VueMathjax)
})
2. 在组件中使用 useHead 加载 MathJax
<template><div class="math-container">
<textarea v-model="formula" placeholder="输入 LaTeX 公式..." rows="3"></textarea><div class="formula-preview">
<vue-mathjax :formula="formula"></vue-mathjax>
</div>
</div>
</template><script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useHead } from '#app'
const formula = ref('$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$')
// ✅ 关键：使用 useHead 动态注入 MathJax 脚本（仅客户端）
useHead({
script: [
{
src: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-AMS_HTML',
defer: true,
// 可选：添加 onload 回调确保初始化完成后再触发渲染
onLoad: () => {
if (typeof window !== 'undefined' && window.MathJax) {
window.MathJax.Hub.Queue(['Typeset', window.MathJax.Hub])
}
}
}
]
})
// 可选：监听公式变化后手动重排版（适用于动态更新场景）
onMounted(() => {
const updateMath = () => {
if (typeof window !== 'undefined' && window.MathJax) {
window.MathJax.Hub.Queue(['Typeset', window.MathJax.Hub])
}
}
// 若需实时预览，可在此处添加防抖逻辑
})
</script><style scoped>
.math-container { margin: 1rem; }
.formula-preview { margin-top: 1rem; font-size: 1.2rem; }
</style>
3. 支持行内与块级公式混合渲染
vue-mathjax-next 支持 $...$（行内）、$$...$$（独立行）及 (...)、[...] 语法。例如：
Cross out the common factor: $dfrac{7}{10}$
Multiply: $dfrac{7}{10} imes dfrac{10}{10}$
Result: $dfrac{70}{100} = 70%$
只需将整段含 LaTeX 的 HTML 字符串传入 :formula 即可自动识别并渲染。
⚠️ 注意事项
- 务必使用 .client.ts 插件后缀：避免 SSR 时尝试访问 window 报错。
- 避免重复加载 MathJax：全局布局（如 app.vue）中加载一次即可，无需每个组件重复注入。
- 版本兼容性：vue-mathjax-next 基于 MathJax 2.x；如需 MathJax 3.x（更轻量、ESM 原生支持），建议改用 mathjax-full + 手动封装，或使用 Nuxt 社区模块 @nuxtjs/mathjax（实验性）。
- 性能优化：对静态公式，可考虑构建时预渲染（如用 markdown-it-texmath）；动态高频更新场景建议添加节流（throttle）。
通过以上配置，你即可在 Nuxt 3 中稳定、高效地渲染任意复杂度的 LaTeX 数学表达式，兼顾开发体验与生产环境可靠性。
