如何配置VSCode Mathjax渲染器解决Markdown公式显示错误问题？

本文共计904个文字，预计阅读时间需要4分钟。

VSCode中Markdown格式出现错误，并非插件未安装，而是MathJax渲染器未正确配置——关键在于配置项是否匹配插件实际行为。

确认你用的是哪个插件在负责 MathJax 渲染

VSCode 没有原生 MathJax 支持，所有公式渲染都依赖扩展。但不同插件读取的配置项完全不同，混用会导致静默失效：

• markdown-preview-enhanced 插件读取 markdown-preview-enhanced.mathRenderingOption，值必须是 "MathJax" 或 "KaTeX"
• markdown-it-math 或 Markdown All in One（旧版）可能依赖 markdown.extension.math.enabled
• LaTeX Workshop 本身不渲染 Markdown 中的公式，它只管 .tex 文件；如果你在 .md 里写公式却启用了它，反而可能干扰预览

执行 Ctrl+Shift+P → 输入 Extensions: Show Installed Extensions，确认当前启用的数学相关扩展名，再查对应文档的配置字段，别凭印象改 settings.json。

mathRenderingOption 配置必须显式指定为 MathJax

即使你装了 markdown-preview-enhanced，默认也不开 MathJax —— 它默认用 KaTeX。公式报错（比如显示 $\int x dx$ 原样、或控制台报 undefined is not a function）大概率是这一步漏了：

• 打开 settings.json（Ctrl+, → 右上角 `{}` 图标）
• 添加这一行（注意逗号位置）："markdown-preview-enhanced.mathRenderingOption": "MathJax"
• 不要写成 "mathRenderingOption": "MathJax" —— 缺少前缀会无效
• 重启预览：右键 Markdown 文件 → Markdown Preview Enhanced: Open Preview to the Side，别用原生 Ctrl+Shift+V

公式语法和定界符必须与插件要求一致

同一个插件，不同版本对定界符的容忍度差异很大。2026 年主流版本（v6.0+）默认只认以下两种：

• 行内公式：$E = mc^2$（单个 $ 包裹，前后不能有空格）
• 块级公式：$$\int_0^1 x^2 dx$$（连续两个 $，且独占一行或前后是空白行）
• 禁用 \[ ... \] 和 $$ ... $$ 混用：某些配置下 $$ 被识别为 HTML 注释，直接跳过解析
• 避免在公式内用中文标点或全角符号，比如 $x＝y$（全角等号）会导致 MathJax 解析中断

MathJax CDN 加载失败时的兜底方案

国内网络常因 MathJax 官方 CDN（https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js）不稳定导致公式空白或控制台报 net::ERR_CONNECTION_TIMED_OUT：

• 在 settings.json 中显式指定国内可用源："markdown-preview-enhanced.mathjaxV3ScriptSrc": "https://unpkg.zhimg.com/mathjax@3.2.2/es5/tex-mml-chtml.js"
• 或者改用本地加载：下载 mathjax-3.x.zip 解压到项目根目录 ./mathjax/，然后设 "markdown-preview-enhanced.mathjaxV3ScriptSrc": "./mathjax/es5/tex-mml-chtml.js"
• 改完后务必执行命令：Markdown Preview Enhanced: Clear Cache，否则旧缓存会掩盖修复效果

最易被忽略的一点：插件不会自动重试失败的 MathJax 加载。一旦首次预览失败，后续所有公式都会卡在“未初始化”状态，必须清缓存 + 重启预览窗口才能恢复。