最常见原因是markdown.math.enabled未启用或vs code版本低于1.84；需在settings.json中添加布尔值"markdown.math.enabled": true，且确保文件为.md后缀、无其他扩展接管预览。
为什么原生预览里公式还是显示为原始代码
最常见原因是 markdown.math.enabled 没启用，或者 VS Code 版本低于 1.84 —— 这个配置项在旧版里根本不存在，开了也无效。不是插件没装、不是语法写错，就是开关没打开。
检查方式很简单：Ctrl+Shift+P → 输入 Preferences: Open Settings (JSON)，确认里面有这一行：
"markdown.math.enabled": true
注意：必须是 true（布尔值），不能写成 "true"（字符串），否则静默失效。
如果已开启仍不生效，再看两点：
- 确保你用的是
.md文件后缀，且文件未被其他扩展强制接管预览逻辑（比如某些 Markdown 插件会禁用原生预览） - 公式语法必须干净：行内用
$E = mc^2$，块级用$$int_0^1 x^2 dx$$；混入中文全角符号、反引号、多余空格都会导致 KaTeX 解析失败
如何让多行对齐、带编号的公式正常工作
原生 KaTeX 支持有限，egin{align}、 ag{1} 这类高级语法默认不识别。必须手动注入 KaTeX 宏定义和扩展能力，靠 settings.json 配置补足。
在 settings.json 中加入：
"markdown.extension.katex.macros": {
"\RR": "\mathbb{R}",
"\abs": ["\left|#1\right|", 1],
"\norm": ["\left\|#1\right\|", 1]
}
同时启用 KaTeX 的 autoNumber 和 displayMath 扩展：
"markdown.extension.katex.options": {
"throwOnError": false,
"displayMath": true,
"autoNumber": "all"
}
⚠️ 注意：markdown.extension.katex.options 是 Markdown All in One 扩展专用配置，不是原生设置。如果你只开了原生预览，这个字段完全不起作用。
离线Markdown转PDF转换器，基于Pandoc与WeasyPrint，支持完整Unicode及本地表情缓存，可将Markdown转为专业级PDF...
验证是否生效：写一段 egin{align} a &= b + c \ d &= e - f end{align}，预览里应自动编号并正确对齐。
导出 PDF 时公式丢失或糊成一团
VS Code 原生不支持导出含公式的 PDF —— 它连 HTML 渲染都依赖浏览器环境，而 PDF 导出插件（如 Markdown PDF）多数用无头 Chromium 截图，KaTeX 渲染完成前就截图，结果就是公式没加载出来，只剩源码。
可行解法只有两个：
- 用
Markdown Preview Enhanced插件，右键 →Markdown Preview Enhanced: Export to PDF，它会在导出前等待 KaTeX 渲染完成 - 改用命令行工具：先用
mdpdf或pandoc+katexCLI 渲染，绕过 VS Code 的预览链路
别信“一键导出”宣传——只要插件没显式声明支持 KaTeX 同步渲染，导出 PDF 就大概率翻车。尤其当公式里有 label、
ef 这种交叉引用时，原生流程根本无法处理。
Mac 和 Windows 下 KaTeX 渲染差异怎么调平
差异主要来自字体回退链和系统默认字号。Mac 上 KaTeX 默认用 STIX Two Math，Windows 常 fallback 到 Segoe UI Symbol，导致 ∑、∫ 等符号粗细/高度不一致，PDF 导出时更明显。
统一做法是在 settings.json 中硬编码字体：
"markdown.extension.katex.options": {
"fontMetrics": {
"metrics": "STIXTwo",
"defaultSize": 16
}
}
但更稳妥的是放弃跨平台像素级一致，转而关注语义正确性：只要 rac{a}{b} 能被解析、排版结构合理、字号可读，就不要强求 Mac 和 Win 渲染完全一样。
真正容易被忽略的点是：KaTeX 的 fontMetrics 配置只对 Markdown All in One 有效，原生预览不认这个字段；而 Markdown Preview Enhanced 默认用 MathJax，要切 KaTeX 得在它的专属配置文件里设 "mathRenderingOption": "KaTeX"。
