markdown-pdf 导出 PDF 时那个默认页眉页脚总让人头疼顶部横着文件名和日期底部还带页码跟文档排版完全不在一个调性上。照着网上教程在 VS Code 的 settings.json 里把markdown-pdf.displayHeaderFooter改成 false再导出一次页眉页脚居然原封不动。这种配置失效的排障往往比写文档更费神我现在的习惯是直接交给走 TaoToken 接入的 Codex 来查。先到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建一把 API Key把 Codex 的 Base URL 指到 https://taotoken.net/api注意末尾不要带 /v1然后在对话里描述「displayHeaderFooter 改 false 后仍显示页眉页脚」让它对照插件文档逐项排查 settings.json。这篇文章就把整个排障过程写清楚包括我会给 Codex 的提示词、Codex 给出的配置对照表以及最终能让页眉页脚真正消失的配置写法。1. 页眉页脚改不掉的三种典型病征1.1 先确认你看到的到底是页眉还是页脚markdown-pdf 的页眉页脚不是 Markdown 文本里的内容而是 Chromium 打印引擎在渲染 PDF 时自动附加的页面信息。默认行为下页眉左侧显示文档标题或文件名右侧显示日期页脚中间显示「第 x 页 / 共 y 页」。如果你看到的是这些内容那确实由displayHeaderFooter控制。但有一种情况容易被误判Markdown 正文里用 HTML 写了header或footer标签或者用 Markdown Preview Enhanced 的预览样式渲染出装饰性横线。这些不是打印引擎生成的页眉页脚改displayHeaderFooter当然没用。先右键导出 PDF用 PDF 阅读器看一下页眉页脚所在的物理位置如果它在页面边缘外侧、紧跟纸张边界那就是打印引擎附加的排障方向才对。1.2 settings.json 里最常见的三种错误配置不生效绝大多数时候不是工具的问题而是 JSON 本身写错了。以 displayHeaderFooter 为例常见错误有三种。第一种是键名缺了插件前缀直接写displayHeaderFooter: false。VS Code 的 settings.json 是全局命名空间所有插件的配置都混在一起markdown-pdf 只会读取以markdown-pdf.开头的键。你写的裸键名会被 VS Code 当作未知配置收藏起来插件根本看不见。第二种是键名大小写或分隔符错误比如markdown-pdf.displayheaderfooter、markdown-pdf.display-header-footer。JSON 键是区分大小写的插件严格按markdown-pdf.displayHeaderFooter去取拼错一个字母就静默失效。第三种是把布尔值写成了字符串markdown-pdf.displayHeaderFooter: false。某些版本会严格校验类型非布尔值直接忽略。这几种错误靠人眼反复看很难发现但丢给 Codex 做字符串级比对几秒钟就能定位。1.3 确认你改的是不是真正生效的那份配置VS Code 的配置有三层用户设置、工作区设置、文件夹设置。如果你在项目里建了.vscode/settings.json它的优先级高于用户设置。很多团队模板会在工作区配置里把markdown-pdf.displayHeaderFooter显式设为 true你在用户设置里改成 false 是压不过它的。排障第一步按CtrlShiftP输入Open Settings (JSON)打开用户设置再检查项目根目录下有没有.vscode/settings.json以及家里有没有其他 VS Code 窗口把同一个文件所在文件夹打开了。工作区配置会浮在用户配置之上这个优先级关系不搞清楚后面所有改动都可能被覆盖。2. 把排查交给 Codex先给 TaoToken 一把 Key2.1 到 TaoToken 创建 API Key要让 Codex 帮你查配置先给它配一个能用的模型通道。打开 TaoToken注册之后进入控制台创建 API Key复制出来的密钥长这样YOUR_API_KEY。这个 Key 是 Codex 调用模型时使用的凭证也是后面在 TaoToken 控制台查看调用量的依据。拿到 Key 之后不要贴进任何公开仓库先放到环境变量里。TaoToken 在这里充当的是一个统一接入通道你不需要纠结模型厂商的各种 Base URL 差异也不用在多个控制台之间来回拷 Key。在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的模型广场里挑一个支持 Codex 的模型 ID记下来后面填进 Codex 配置。2.2 在 Codex 配置里换成 TaoToken 的 Base URLCodex 的配置写在~/.codex/config.toml。如果你之前用过官方通道需要把模型供应商整段替换。先设置环境变量再改配置文件。export TAOTOKEN_API_KEYYOUR_API_KEYmodel YOUR_MODEL_ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY注意两点。第一base_url填的是 https://taotoken.net/api末尾不要加/v1这是接口地址不是给人点的官网链接。第二model填YOUR_MODEL_ID具体值以 TaoToken 模型广场当时列出的模型 ID 为准不要凭记忆写版本号。配置保存后在终端任意提一个跟 VS Code 配置无关的小问题确认 Codex 能正常回复再进入下一步排障。2.3 验证 Codex 是否真的走了 TaoToken验证不需要额外写代码直接在 Codex 里问一句「你现在用的 base_url 是什么」就能从回复里确认通道是否切换成功。也可以让它读一下~/.codex/config.toml看model_provider是否指向taotoken。如果 Codex 一直报连接错误优先检查环境变量名是否和env_key完全一致以及 base_url 是否误加了/v1。通道通了后面所有配置排查才有意义。3. 在 Codex 里描述 markdown-pdf 配置病征3.1 给 Codex 的排障提示词配置好通道后把问题描述给 Codex。不要只丢一句「页眉页脚关不掉就」那样它只能给泛泛的猜测。我是这样写的我在 VS Code 里使用 markdown-pdf 插件导出 PDF。 用户设置里已经写了 markdown-pdf.displayHeaderFooter: false 但导出后的 PDF 顶部仍有文件名和日期底部仍有页码。 以下是我 settings.json 里与 markdown-pdf 相关的全部配置 把你的 JSON 片段贴在这里 请逐项核对 1. 这些键名是否与 markdown-pdf 官方配置完全一致 2. displayHeaderFooter 的值类型是否是布尔 false 3. 是否还有 headerTemplate / footerTemplate 或其他配置会覆盖这个开关 4. .vscode/settings.json 里的同名配置是否会覆盖用户设置。这段提示词把现象、已知配置、怀疑点全部交代清楚。Codex 拿到之后会先做三件事检查键名前缀、检查值类型、检查配置层级。这些步骤看起来简单但手写检查很容易漏尤其是当 settings.json 里有几百行配置时。3.2 让 Codex 输出「配置现状 vs 插件默认值」对照表原文教程里提到markdown-pdf 共有 34 条配置大多数保持默认就好。排障时最怕的就是这 34 条之间的相互影响。我让 Codex 把配置拆成对照表每一行列配置键、当前值、默认值、是否影响页眉页脚最后一行给结论。配置键当前值默认值作用markdown-pdf.displayHeaderFooterfalsetrue是否显示打印引擎附加的页眉页脚markdown-pdf.headerTemplatediv/div空模板页眉内容模板markdown-pdf.footerTemplatediv/div空模板页脚内容模板markdown-pdf.styles未设置[]PDF 渲染样式不影响页眉页脚开关Codex 通常会给出类似这样的结论displayHeaderFooter键名和值类型都正确但headerTemplate或footerTemplate里若残留非空字符串某些版本下即便开关为 false模板内容仍可能被渲染到 PDF 边缘。这个提醒很关键因为很多人只改了开关没管模板。3.3 常见误判Markdown Preview Enhanced 的导出入口还有一个高频误判点。原文里提到的 Markdown Preview Enhanced 也能导出 PDF但它的导出走的是另一套渲染流程跟 markdown-pdf 的displayHeaderFooter完全没有关系。如果你在 md 文件预览窗口里右键导出 PDF看到的是 Markdown Preview Enhanced 的导出菜单那条路径的页眉页脚由预览主题和打印参数控制改 markdown-pdf 配置当然不生效。让 Codex 排查时会让它查看导出菜单的来源。正确做法是在资源管理器的文件列表里右键.md文件选择Markdown PDF: Export (pdf)。如果右键菜单同时出现多个「导出 PDF」选项选带 Markdown PDF 图标的那个。Codex 在对话里也会帮你区分这两条导出链路的差异避免你反复改配置却始终在错误的入口验证。4. 按 Codex 的结论修正 settings.json 并验证4.1 能直接用的配置片段如果settings.json没被工作区配置覆盖Codex 给出的最终修正结果长这样。把下面这段合并进你的用户设置 JSON 里注意displayHeaderFooter前面必须带markdown-pdf.前缀。{ markdown-pdf.type: pdf, markdown-pdf.outputDirectory: pdf, markdown-pdf.outputDirectoryRelativePathFile: true, markdown-pdf.displayHeaderFooter: false, markdown-pdf.headerTemplate: , markdown-pdf.footerTemplate: }headerTemplate和footerTemplate显式置空是为了避免某些版本下残留模板内容被渲染出来。type保持pdf对应原文里的导出格式默认值。outputDirectory可以按你的习惯改它不影响页眉页脚。4.2 验证路径右键导出 PDF 看页眉页脚配置保存后先重启 VS Code 窗口再用正确入口导出。在资源管理器里右键目标.md文件选择Markdown PDF: Export (pdf)。导出完成后用 PDF 阅读器打开把视图缩放到整页重点看页面顶部边缘有没有文件名和日期、底部边缘有没有页码。如果这两块区域完全空白说明displayHeaderFooter已经生效。这次验证一定要在正确的入口做不要在 Markdown Preview Enhanced 的预览窗口里右键导出。很多教程贴图都是从那个入口导的配置却写在 markdown-pdf 里两边对不上给人一种「改也没用」的错觉。4.3 如果还显示按顺序做三件事页眉页脚仍在的话先不要急着改配置。按下面顺序排查每做完一步导一次 PDF。第一CtrlShiftP输入Developer: Reload Window重载 VS Code 窗口。插件配置在窗口启动时读取改动 settings.json 后未重载旧配置会一直驻留内存。第二检查当前项目是否存在.vscode/settings.json。如果有打开看里面有没有markdown-pdf.displayHeaderFooter工作区设置优先级高于用户设置你写在用户设置里的 false 压不过它。把工作区里的值也改成 false或者直接删除那一行让用户设置生效。第三确认导出菜单是 markdown-pdf 生成的。有些环境同时装了多个 Markdown 相关插件右键菜单会出现重复的导出 PDF 项。点名称带Markdown PDF: Export (pdf)的项不要点 Markdown Preview Enhanced 的导出按钮。这一步做完绝大多数页眉页脚残留问题都会消失。5. 把这次排障沉淀成 VS Code Markdown 检查清单5.1 配置前先看插件默认值这次排障能快速收敛靠的是让 Codex 逐项对比配置现状和插件默认值而不是凭感觉改。以后配置其他 VS Code Markdown 插件也可以用同样方法先打开CtrlShiftP→Open Default Settings (JSON)搜索插件名前缀把默认值记下来再决定改哪几项。原文里提到的 markdown-all-in-one、markdown toc、markdownmath、Markdown Preview Enhanced它们的配置键都遵循同样的插件前缀规则排障思路完全通用。你甚至可以在提示词里直接要求 Codex「先列出 markdown-pdf 所有与页眉页脚相关的配置键和默认值再对照我的 settings.json 给出差异」。这样得到的答案带着依据不是拍脑袋猜的。排障最后Codex 会建议你把 settings.json 里无关的配置清理掉保留最小必要项类似我们最后留下的那五条配置。配置越少未来相互覆盖的概率越低。5.2 验证通过后回 TaoToken 对一下这次调用排障到这里Codex 已经帮你把配置理顺了页眉页脚这类问题以后可以自己照着查。如果后续还想让 Codex 继续处理其他 VS Code Markdown 插件配置可以在 TaoToken 模型对话 里先用同一把 Key 发一条测试消息确认模型 ID 和 Base URL 没有填错。需要长期写代码的话可以打开 Coding Plan 看套餐是否够用还没创建 Key 的直接去 控制台 API Keys 补一把。回控制台看一眼这次排障调用的用量心里有数下次排查才不慌。
