企业官网建设流程全解析

当 Markdown Preview Enhanced 的 LaTeX 公式不渲染时，我是怎么用 Codex 排查的

如果你正在用 VS Code 写 Markdown，并且装了 Markdown Preview Enhanced（后面简称 MPE），大概率遇到过这种场景：明明在文档里写了$E=mc^2$或者$$...$$的公式块，侧边预览里却只显示一串原始文本，公式该有的排版一点没出来。更让人困惑的是，有些高亮语法（比如==高亮==）在 VS Code 自带的 Markdown 预览里根本看不到效果，只有在 MPE 自己的预览窗口里才生效。这就带来一个很实际的问题：到底是公式语法写错了，还是插件没启用对应功能，还是预览命令用错了？

这篇就围绕这个排障场景展开。做法不是让 TaoToken 去渲染公式——它不负责这件事——而是先打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建一个 Key，再把 Codex 的 Base URL 配成 https://taotoken.net/api，让 Codex 对照 MPE 的功能清单，帮我逐条排查公式语法、插件启用状态和预览命令。TaoToken 在这里只提供模型通道和 Key，渲染仍然由 MPE 自己完成。

一、原问题与场景：公式不显示，问题可能出在三个地方

MPE 的 LaTeX 支持是它相对 VS Code 内置预览的一个明显优势。内置预览对数学公式的支持有限，而 MPE 通过集成 KaTeX 之类的渲染引擎，可以正常显示行内公式和块级公式。但正因为功能多，出问题的入口也多。

我遇到的典型症状是这几类：

第一类，公式语法本身有问题。比如行内公式写成了$ E=mc^2$（美元符号后多了空格），或者块级公式的$$没有单独成行，导致解析器把它当成普通文本。Markdown 的公式解析对边界字符比较敏感，一个多余的空格就可能让整段失效。

第二类，插件功能没启用。MPE 的很多能力是可以通过配置开关控制的，比如markdown-preview-enhanced.enableExtendedTableSyntax、markdown-preview-enhanced.enableCriticMarkupSyntax这类选项。如果某个语法对应的开关是关的，预览里自然看不到效果。高亮文本只在 MPE 预览可见，也是因为它是 MPE 的扩展语法，而不是标准 Markdown。

第三类，预览命令用错了。VS Code 里打开预览有好几种方式：内置的Markdown: Open Preview、Markdown: Open Preview to the Side，以及 MPE 自己的Markdown Preview Enhanced: Open Preview。如果你点的是内置预览，那 MPE 的扩展语法和部分公式渲染就不会生效。这个坑非常常见，因为两个命令的名字很像。

这三类问题的共同点是：光看现象很难判断根因。公式不显示，可能是语法错，也可能是预览窗口不对。这时候如果有一个能读懂 MPE 文档、能对照功能清单逐条核对的助手，排查效率会高很多。Codex 配合 TaoToken 的模型通道，就是干这个的。

二、TaoToken 前置：先拿到 Key，再配通 Codex

在开始排查之前，需要先把模型通道准备好。TaoToken 的角色很明确：它提供 API 通道和 Key，让你能在 Codex 这类工具里调用模型。它不参与 Markdown 渲染，也不替代 MPE。

第一步，打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ，注册并创建一个 API Key。这个 Key 就是后面配置里要填的YOUR_API_KEY。

第二步，记住 API 地址是 https://taotoken.net/api 。注意这个地址不带任何查询参数，配置 Base URL 时直接用这个。

第三步，如果你用的是 Codex CLI，可以通过 npm 安装：

npm i -g @taotoken/taotoken

然后用一行命令启动：

taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m MODEL_ID

这里的MODEL_ID填你在 TaoToken 控制台里选定的模型标识。如果你更习惯手动改配置文件，Codex 的配置走的是config.toml，下面会给出手动配置的写法。

需要强调的是，这一步只是把模型通道打通。真正排查 MPE 的公式问题，还是要靠 Codex 去读文档、对照配置项。TaoToken 提供的是“能问问题的通道”，不是“自动修好渲染的魔法”。

三、可复制配置：Codex 的 config.toml 与 MPE 的 settings.json

这一节给两份配置。一份是 Codex 侧的，用来接通 TaoToken；一份是 MPE 侧的，用来确保公式相关功能是开着的。

先说 Codex 的config.toml。在 Codex 的配置目录下（通常是~/.codex/config.toml或项目级配置），写入类似内容：

model = "MODEL_ID" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY"

然后在环境变量里设置：

export TAOTOKEN_API_KEY=YOUR_API_KEY

这样 Codex 就会通过 TaoToken 的通道调用模型。配置完成后，你可以直接在 Codex 里提问，比如“Markdown Preview Enhanced 的 LaTeX 公式需要哪些配置项才能正常渲染”。

再说 MPE 侧。MPE 的配置在 VS Code 的settings.json里，键名以markdown-preview-enhanced.开头。和公式、扩展语法相关的几个关键项：

{ "markdown-preview-enhanced.enableExtendedTableSyntax": true, "markdown-preview-enhanced.enableCriticMarkupSyntax": true, "markdown-preview-enhanced.mathRenderingOption": "KaTeX", "markdown-preview-enhanced.enableEmojiSyntax": true }

其中mathRenderingOption控制公式渲染引擎，常见取值是KaTeX或MathJax。如果你发现公式完全不渲染，先确认这一项不是空值或被设成了None。enableEmojiSyntax对应的是表情符号，原文里提到表情符号只在 MPE 预览窗口可见，就是这个开关在起作用。

把这两份配置放好，就具备了排查的基础环境：Codex 能通过 TaoToken 回答问题，MPE 的公式相关开关也处于可控状态。

四、验证请求与成功结果：让 Codex 对照功能清单排查

配置好之后，怎么验证这套组合是通的？分两步。

第一步，验证 Codex 能通过 TaoToken 正常返回。在 Codex 里发一个简单请求，比如让它解释 MPE 的mathRenderingOption有哪些可选值。如果能看到结构化的回答，说明通道是通的。这一步的成功标志是：Codex 能准确说出 KaTeX 和 MathJax 的区别，而不是泛泛而谈。

第二步，用 Codex 对照 MPE 的功能清单逐条排查。原文里列过 MPE 的能力：目录、批注、合并单元格、插入 LaTeX 公式、用纯文本绘图、运行代码、导入导出、制作幻灯片、高亮文本。其中“高亮文本仅在 MPE 预览可见”这一条，正好对应前面说的预览命令问题。

你可以这样问 Codex：“我的 MPE 里==高亮==不生效，公式也不渲染，帮我按功能清单排查。” Codex 会引导你检查：预览窗口是不是 MPE 自己的、enableCriticMarkupSyntax之类的开关有没有开、公式的$边界有没有写对。

成功的结果是：你能定位到具体是哪一类问题。比如发现是预览命令点错了，改用Markdown Preview Enhanced: Open Preview后公式和高亮同时恢复；或者发现是mathRenderingOption被设成了None，改回KaTeX后公式正常。这时候问题就从“公式不显示”收敛到了“某个具体配置项”。

五、本篇常见错排查

围绕这个场景，有几个高频错误值得单独列出来。

错误一：把内置预览当成 MPE 预览。这是最常见的。VS Code 命令面板里搜 “preview” 会出来一堆，认准带 “Markdown Preview Enhanced” 前缀的那个。内置预览不支持 MPE 的扩展语法，公式渲染行为也可能不同。

错误二：公式的$边界写错。行内公式是$...$，块级是$$...$$且通常要单独成行。$和内容之间不要留空格，$$前后不要混入其他字符。如果公式里有下划线、星号这类 Markdown 特殊符号，必要时用反斜线转义。

错误三：mathRenderingOption没设或设错。这一项如果缺失，MPE 可能不启用公式渲染。确认它是KaTeX或MathJax。

错误四：Codex 的 Base URL 写成了带路径的形式。TaoToken 的 API 地址就是 https://taotoken.net/api ，不要在后面追加/v1之类的路径，除非文档明确要求。config.toml里的base_url和 CLI 里的-u参数都填这个。

错误五：环境变量名和配置里的env_key不一致。config.toml里写了env_key = "TAOTOKEN_API_KEY"，那环境变量就必须是TAOTOKEN_API_KEY，大小写要一致。

错误六：装了 MPE 但没重载窗口。改完settings.json后，VS Code 有时需要重载窗口（Developer: Reload Window）才能让新配置生效。公式不渲染时，先重载一次再判断。

这些错误里，前三个属于 MPE 侧，后三个属于 Codex/TaoToken 侧。排查时可以先分清是哪一侧的问题，再往下查。

六、语义一致的 CTA

如果你已经跟着配通了 Codex，接下来最该做的是把 Key 和接入文档放在手边。创建和管理 Key 的入口在 API Keys 页面，接入细节看接入文档。这两个地方能解决大部分“Key 填哪、Base URL 怎么写”的问题。

如果你主要是在验证模型能不能正确回答 MPE 配置类问题，可以直接去模型对话页面试几轮，确认通道稳定。

如果你打算长期用 Codex 做编码和文档排查，比如反复对照 MPE 功能清单、检查settings.json、排查公式语法，那 Coding Plan 会更合适，省得每次单独配。

回到这个场景本身：MPE 的 LaTeX 不显示，根因往往不在公式本身，而在预览命令、配置开关或语法边界。TaoToken 提供的是让 Codex 能帮你查规则的通道，渲染始终是 MPE 的事。把 Key 配好，把问题问清楚，公式该出来的时候就会出来。