VSCode本身不提供离线文档打包导出功能，所谓「离线文档」需一体化归档Markdown文件、渲染效果及依赖资源（如图片、CSS、Mermaid生成的SVG），直接ZIP文件夹会漏掉渲染逻辑、字体fallback和样式隔离，导致PDF乱码、HTML空白、Mermaid图消失。
VSCode 本身不提供“离线文档打包导出”功能，所谓「离线文档」通常指本地 Markdown 文件 + 预览渲染效果 + 依赖资源（如图片、CSS、Mermaid 图生成的 SVG）的一体化归档。直接右键导出或用系统压缩会漏掉渲染逻辑、字体 fallback、样式隔离等关键环节——结果是 PDF 乱码、HTML 打不开、PNG 截图失真。
为什么不能直接 zip 整个文件夹就完事
常见错误现象：把 .md 文件和同目录的 images/ 一起压缩，发给同事后对方打开 HTML 显示空白，PDF 中文全是方框，Mermaid 图消失。
- VSCode 的 Markdown 预览依赖内置的
markdown-it引擎和 Chromium 渲染上下文，不是纯静态文件组合 -
Export to PDF实际调用的是 Puppeteer 截取 DOM 快照，不是转换源码；没开预览窗就导出 = 截一张白页 - 导出的 HTML/PDF 里引用的字体、CSS 路径是相对的，但压缩包解压后若路径层级变动（比如多了一层
archive/），链接立刻失效 - Mermaid 图在导出时需实时渲染成 SVG，而 SVG 是内联在 HTML 中的，不是独立文件——你 zip 时根本看不到它
真正能离线交付的三种导出方式
必须明确目标用途，再选路径：
- Pdf Exporter 插件：适合交付正式文档，生成单文件 PDF，自带中文字体 fallback 和页眉页脚，但不保留交互（如可点击的 TOC 锚点）
-
Markdown Preview Enhanced（MPE）+
Export to HTML：适合发布到内网静态站，输出含完整 CSS、内联 SVG、MathJax 的 HTML，但需确保stylesheet路径为相对路径且随包一起分发 - 手动「打印为 PDF」：最轻量，不依赖插件，打开 MPE 预览窗 →
Ctrl+P→ 选择“另存为 PDF”，能保留页面缩放、代码块高亮、公式排版，但无法自定义 margin 或字体
注意：Markdown PDF 插件已彻底失效（2026 年起无法渲染中文和 Mermaid），别试。
导出前必须检查的三个配置项
哪怕用了 MPE，跳过这三步，离线包大概率打不开或显示异常：
- 确认
.md文件顶部有 YAML front matter，至少包含：pdf_options: {format: 'A4', margin: {top: '20mm'}}—— 缺少它，导出的 PDF 页边距可能为零，文字被裁切 - CSS 文件（如
style.css）必须和.md在同一级目录，且 YAML 里写的是stylesheet: ./style.css，不能是./css/style.css或绝对路径 - 所有图片引用必须用相对路径，例如
，不能是../assets/diagram.png或 URL；否则导出的 HTML 里
如何验证导出结果是否真正离线可用
别只看自己电脑上能打开，要模拟真实离线环境：
- 把生成的
output.html或doc.pdf单独复制到另一台没装 VSCode 的机器，双击打开 —— HTML 应完整渲染，无控制台报错；PDF 应无方框、公式清晰、目录可点击 - 用浏览器打开 HTML 后按
F12，检查 Network 面板：所有资源（CSS、JS、图片、SVG）状态码都是200，没有file://协议报错或跨域拦截 - 在 PDF 查看器里搜索文档中的任意中文关键词，应能定位 —— 若搜不到，说明导出时没嵌入字体或用了不可搜索的位图渲染
最容易被忽略的是：MPE 导出 HTML 时默认不内联 CSS，而是用 外链。这意味着你 zip 时漏掉 style.css，HTML 就只剩裸文本。务必手动检查生成的 HTML 源码开头是否有 标签，并确认对应文件已包含在压缩包中。
