1. 公式渲染异常的现场还原与定位思路VSCode 里用 Markdown Preview Enhanced 写技术笔记最让人抓狂的场景之一就是行内公式$Emc^2$在预览窗口里原样吐出来或者干脆变成一串红色报错。这个问题的核心检索词是VSCode Markdown Preview Enhanced KeTaX 数学公式渲染异常它本质上不是 Markdown 语法写错了而是预览链路里负责把 LaTeX 转成 HTML 的那一环没跑起来。Markdown Preview Enhanced后面简称 MPE渲染公式的流程大致是这样你在.md文件里写下$...$或$$...$$MPE 捕获这些片段交给配置里指定的数学引擎去解析。MPE 支持两个引擎一个是KaTeX注意官方拼写是 KaTeX很多人写成 KeTaX配置项里也是katex另一个是MathJax。KaTeX 渲染快、体积小是默认选项MathJax 兼容性更广但加载慢。当引擎加载失败、版本不匹配、或者配置项被写错时公式就会渲染异常。适合读这篇的人有三类一是刚装好 MPE 发现公式不显示的新手二是升级 VSCode 或插件后公式突然坏掉的老用户三是想把公式渲染链路彻底搞明白、以后能自己排障的进阶用户。我试过在几台机器上复现发现触发条件高度集中在「数学引擎配置」和「预览进程状态」这两块。先做一次最小复现确认问题边界。新建一个formula-test.md内容如下# 公式测试 行内公式$a^2 b^2 c^2$ 块级公式 $$ \int_{0}^{\infty} e^{-x^2} dx \frac{\sqrt{\pi}}{2} $$用 MPE 打开预览快捷键CtrlK V或右键选 Markdown Preview Enhanced: Open Preview。如果行内公式显示为源码、块级公式显示为灰色代码块说明数学引擎没生效。这时候别急着重装先按下面的顺序排查能省掉大量无效操作。第一步确认当前用的引擎。打开 VSCode 设置Ctrl,搜索markdown-preview-enhanced找到Math Rendering Option这一项。它有三个可选值KaTeX、MathJax、None。如果被设成了None公式当然不渲染改成KaTeX即可。这一步能解决相当一部分「公式不显示」的问题。第二步看预览进程有没有卡死。MPE 的预览是一个独立的 webview 进程有时候它加载到一半崩了界面还停在那里但渲染管线已经断了。这时候执行命令面板CtrlShiftP里的Markdown Preview Enhanced: Close Preview再重新打开往往就恢复了。第三步检查是不是被其他 Markdown 插件抢了渲染权。VSCode 里如果同时装了内置 Markdown 预览、Markdown All in One、MPE快捷键可能触发的是内置预览而不是 MPE。内置预览对 KaTeX 的支持和 MPE 不一样表现就是公式时好时坏。确认标题栏显示的是 MPE 的预览界面而不是 VSCode 原生预览。第四步才是考虑版本问题。MPE 依赖内置的 KaTeX 资源如果插件版本和 VSCode 版本跨度过大资源加载路径可能失效。这时候升级或回退插件版本能解决但这是最后手段不是首选。把这四步走完大部分公式渲染异常都能定位到具体原因。接下来讲怎么用 TaoToken 把配置和验证流程固化下来避免每次换机器都重新踩一遍。2. TaoToken 前置准备把模型能力接进排查链路公式渲染本身是本地行为为什么要在排查流程里引入 TaoToken因为当公式渲染异常时你往往需要快速验证「是 Markdown 语法问题还是渲染引擎问题」。这时候如果能有一个稳定的模型接口把出问题的公式片段丢进去让它解释语法、给出修正建议排查效率会高很多。TaoToken 在这里扮演的是「排查助手」的角色不是渲染引擎本身。TaoToken 是一个聚合式的大模型 API 接入服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它能做什么提供统一的 API 入口让你用一套 Key 调用多种模型适合谁需要在自己工具链里嵌入模型能力、又不想分别对接多家平台的开发者。对于这篇的场景你可以用它来快速问「这段 LaTeX 为什么在 KaTeX 里报错」。先说清楚边界TaoToken 不参与公式渲染它只是帮你诊断公式语法。渲染还是靠 MPE 本地的 KaTeX。这个定位要摆正否则会走偏。前置准备分三步。第一步拿到 API Key。访问 https://taotoken.net/api-keys 登录后创建一个 Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。第二步确认 API 基础地址。TaoToken 的 API 入口是 https://taotoken.net/api 所有请求都基于这个地址拼接路径。比如对话补全的路径是/v1/chat/completions完整地址就是https://taotoken.net/api/v1/chat/completions。这个地址在后面的配置片段里会反复用到。第三步选一个模型 ID。TaoToken 支持多种模型具体可用列表在 https://taotoken.net/doc 里查。排查公式语法这种任务选一个擅长代码和结构化文本的模型就行。记下模型 ID比如claude-sonnet-4-5这类后面配置里要填。如果你只是想临时问几个公式问题用网页版模型对话就够了地址是 https://taotoken.net/model-conversation?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把报错的公式贴进去问「这段 LaTeX 在 KaTeX 下为什么渲染失败」通常能直接得到答案。但如果你想把这种诊断能力固化到本地工具链里比如写个脚本自动检查 Markdown 文件里的公式那就需要 API Key 和下面的配置。长期做编码和 Agent 类任务的可以看 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。前置准备做完你手里应该有三样东西API Key、Base URLhttps://taotoken.net/api、Model ID。这三件套是后面所有配置的基础缺一不可。下一节把它们写进具体的配置文件里。3. 可复制的 settings 片段与三件套配置这一节是全文的操作核心。我会给出 MPE 的 settings 片段、TaoToken 的三件套配置以及一个用脚本调用模型检查公式的示例。所有片段都可以直接复制路径和字段名保持和实际一致。先处理 MPE 的公式渲染配置。VSCode 的用户设置文件在settings.json路径因系统而异Windows 是%APPDATA%\Code\User\settings.jsonmacOS 是~/Library/Application Support/Code/User/settings.jsonLinux 是~/.config/Code/User/settings.json。用CtrlShiftP执行Preferences: Open User Settings (JSON)也能直接打开。把下面这段合并进你的settings.json{ markdown-preview-enhanced.mathRenderingOption: KaTeX, markdown-preview-enhanced.mathInlineDelimiters: [ [$, $], [\\(, \\)] ], markdown-preview-enhanced.mathBlockDelimiters: [ [$$, $$], [\\[, \\]] ], markdown-preview-enhanced.enableExtendedTableSyntax: true, markdown-preview-enhanced.previewTheme: github-light.css, markdown-preview-enhanced.scrollSync: true }逐项说明。mathRenderingOption设成KaTeX这是公式能渲染的前提如果之前是None或MathJax改这里。mathInlineDelimiters定义行内公式的定界符默认支持$...$和\(...\)两种保留默认即可。mathBlockDelimiters定义块级公式定界符支持$$...$$和\[...\]。previewTheme选一个浅色主题深色主题下 KaTeX 的某些符号对比度低容易误判成渲染失败。注意一个坑settings.json是 JSON 格式不能有注释不能有尾随逗号。如果你已经有其他配置把上面这些键值对合并进去别整个覆盖。接下来是 TaoToken 的三件套配置。如果你用 Cline、Continue 这类支持自定义 API 的插件配置通常长这样以 Cline 的 MCP 配置为例文件在cline_mcp_settings.json{ mcpServers: { taotoken-helper: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_MODEL_ID: claude-sonnet-4-5 } } } }这里三件套齐全Base URL 是https://taotoken.net/apiAPI Key 填你创建的那串Model ID 填你选的模型。注意 Base URL 不带任何 UTM 参数就是纯 API 地址。如果你用 Claude Code配置走的是环境变量或settings.json。Claude Code 的配置文件在~/.claude/settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Claude Code 的接入文档在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有更细的说明。这里同样三件套齐全Base URL、Key、Model ID 一个不少。如果你用 Codex配置在~/.codex/auth.json{ OPENAI_API_KEY: sk-你的Key, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_MODEL: claude-sonnet-4-5 }三个文件格式不同但核心都是 Base URL Key Model ID 这三件套。记住这个模式换任何工具都是填这三样。最后给一个用脚本调用模型检查公式的示例。写一个check_formula.pyimport requests API_KEY sk-你的Key BASE_URL https://taotoken.net/api MODEL_ID claude-sonnet-4-5 def check_latex(latex_snippet): resp requests.post( f{BASE_URL}/v1/chat/completions, headers{ Authorization: fBearer {API_KEY}, Content-Type: application/json }, json{ model: MODEL_ID, messages: [ {role: user, content: f这段 LaTeX 在 KaTeX 下能正常渲染吗如果有问题请指出并给出修正{latex_snippet}} ] }, timeout30 ) return resp.json()[choices][0][message][content] if __name__ __main__: print(check_latex(r\frac{1}{2}))这个脚本把出问题的公式片段发给模型让它判断 KaTeX 兼容性。跑之前先pip install requests。注意choices字段的读取方式如果返回结构不对说明请求没成功下一节会讲怎么排查。配置写完别急着下结论先做验证。4. 验证请求与成功结果确认配置改完必须逐项验证否则你不知道是配置生效了还是碰巧好了。这一节给出完整的验证动作和预期结果。先验证 MPE 公式渲染。重新打开formula-test.md执行Markdown Preview Enhanced: Close Preview再Open Preview确保用的是新配置。预期结果行内公式$a^2 b^2 c^2$显示为带上下标的数学符号块级公式显示为居中的积分表达式不再是源码或灰色代码块。如果公式渲染正常你会看到a² b² c²这样的排版积分符号和分数都是标准数学字体。如果还是不对回到第 1 节的四步排查重点看mathRenderingOption是不是真的保存成功了。有时候 VSCode 设置界面改了但没保存或者被工作区设置覆盖了。工作区设置优先级高于用户设置检查.vscode/settings.json里有没有冲突项。再验证 TaoToken 的 API 连通性。用 curl 发一个最小请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 OK 两个字母即可}] }预期返回一个 JSON结构里包含choices数组choices[0].message.content是模型回复的内容。如果返回401说明 Key 不对或没带上如果返回404说明路径拼错了检查是不是漏了/v1如果返回model not found说明 Model ID 写错了去 https://taotoken.net/doc 核对。跑通 curl 后再跑第 3 节的check_formula.py。预期输出是一段文字告诉你那段 LaTeX 在 KaTeX 下是否兼容。如果脚本报KeyError: choices说明返回结构里没有choices通常是请求失败但没抛异常打印完整resp.json()看看错误信息。验证 MPE 和 TaoToken 都通了之后做一个联合验证故意写一段 KaTeX 不支持的 LaTeX比如\begin{tikzcd}这是 TikZ 的语法KaTeX 不支持看 MPE 预览里是不是报错再用脚本问模型这段为什么不行。预期结果是 MPE 显示渲染错误模型告诉你 KaTeX 不支持 TikZ 环境建议改用其他方式。这个联合验证能确认两条链路都工作正常。成功结果的标志有三个MPE 预览里公式正常显示、curl 请求返回choices、脚本能给出有意义的诊断。三个都满足说明配置和接入都没问题。如果只满足前两个脚本报错那就是脚本本身的代码问题不是配置问题。验证过程中有个细节要注意MPE 的预览有缓存。改了settings.json后有时候旧预览进程还在用旧配置。稳妥做法是关掉所有预览窗口重启 VSCode再打开预览。这一步能排除大部分「改了没生效」的假象。5. 本篇常见错误逐项排查这一节对照真实报错逐项给出原因和修法。这些报错都是我在实际排查中遇到过的不是编的。报错一401 Unauthorized。出现在 curl 或脚本请求 TaoToken 时。原因通常是 Key 没带、Key 写错、或者Authorization头格式不对。正确格式是Bearer sk-xxxBearer和 Key 之间有一个空格。检查你的 Key 是不是复制时带了空格或换行。如果 Key 确认没错去 https://taotoken.net/api-keys 看这个 Key 是不是被删了或过期了。报错二local proxy failed或连接超时。出现在请求发不出去时。原因可能是网络环境问题或者 Base URL 写错了。确认 Base URL 是https://taotoken.net/api不要多加/v1之外的路径也不要在末尾加斜杠。如果你在脚本里用了系统代理设置检查代理配置是否干扰了请求。这类问题优先用 curl 在终端直接测排除脚本层面的干扰。报错三reading choices或KeyError: choices。出现在解析返回结果时。原因是请求虽然返回了 200但返回体结构不是预期的对话补全格式。可能是 Model ID 写错导致返回了错误信息也可能是请求体字段名写错。打印完整的resp.json()看里面有没有error字段。如果有按错误信息修如果没有choices也没有error检查请求的Content-Type是不是application/json。报错四OAuth相关错误。出现在 Claude Code 或某些需要 OAuth 的工具里。原因是工具走了 OAuth 流程而不是 API Key 流程。Claude Code 用 API Key 接入时要确保ANTHROPIC_API_KEY环境变量设置正确并且没有同时配置 OAuth 相关的字段。如果之前登录过 OAuth清理掉旧的凭证缓存再试。报错五公式显示为源码但mathRenderingOption已经是KaTeX。原因是定界符不匹配。比如你用了\(...\)但配置里没启用这个定界符或者用了$$但被解析成了其他语法。检查mathInlineDelimiters和mathBlockDelimiters配置确保你用的定界符在列表里。另外Markdown 里如果公式前后没有空行块级公式可能被当成普通文本。报错六公式渲染成乱码或符号错位。原因是字体或主题问题。KaTeX 依赖特定数学字体如果预览主题的 CSS 覆盖了字体设置符号会错位。把previewTheme换成github-light.css这类标准主题试试。如果还是乱码检查系统有没有装 KaTeX 需要的字体通常插件会自带但某些精简系统可能缺字体。报错七改了settings.json但预览没变化。原因是工作区设置覆盖了用户设置或者预览进程缓存。先检查项目目录下.vscode/settings.json有没有同名配置项有的话以工作区为准。然后关掉所有预览重启 VSCode。如果还不行执行Developer: Reload Window强制重载。报错八Cline MCP 配置后工具不生效。原因是cline_mcp_settings.json路径不对或 JSON 格式错误。这个文件通常在 Cline 插件的全局存储目录具体路径看插件文档。JSON 里不能有注释和尾随逗号。配置改完要重启 Cline 插件不是重启 VSCode。三件套 Base URL、Key、Model ID 都要填对缺一个都不行。排查时有个通用原则先隔离变量。公式问题就只测公式API 问题就只用 curl 测别把两个混在一起。混在一起排查你分不清是哪个环节出的错。每修一个点就验证一次确认生效再动下一个。6. 把公式排查流程固化下来公式渲染异常这件事本质是「配置 进程 版本」三个变量的组合问题。与其每次出问题重新摸索不如把排查流程固化成一个清单下次直接照着走。我的做法是在项目根目录放一个formula-debug.md里面记录当前机器的 MPE 配置、TaoToken 三件套、以及最近一次正常渲染的时间。出问题时先对比配置有没有变再按第 1 节的四步走一遍。这个习惯帮我省了很多重复劳动。另一个实用技巧是把公式检查脚本挂到 Git pre-commit 钩子上。每次提交 Markdown 前自动扫描文件里的$...$片段调用 TaoToken 检查 KaTeX 兼容性不兼容就阻止提交。这样公式问题在写的时候就暴露不会等到预览时才发现。脚本可以基于第 3 节的check_formula.py改加上文件遍历和退出码逻辑。如果你经常换机器把settings.json里的 MPE 配置和 TaoToken 三件套抽成一个片段存在 dotfiles 仓库里新机器一键同步。这样公式渲染环境始终一致不会出现「这台机器好那台机器坏」的情况。最后提醒一点KaTeX 和 MathJax 的语法支持范围不同。KaTeX 快但不支持 TikZ、某些宏包MathJax 慢但兼容性广。如果你的笔记里有复杂图表可能需要切到 MathJax。切换方式就是改mathRenderingOption的值其他配置不用动。选哪个取决于你的公式复杂度没有绝对优劣。把上面这些做完你的 VSCode 公式渲染链路就稳了。下次再遇到公式不显示先看mathRenderingOption再看预览进程最后才怀疑版本。这个顺序能覆盖九成以上的情况。