VSCode怎么配置Markdown写作和预览环境

VS Code Markdown 预览问题主要由三个配置导致：自动刷新需开启 markdown.preview.autoRefresh 和 markdown.preview.refreshOnSa ve；数学公式需启用 markdown.math.enabled 并规范语法；代码块高亮依赖准确语言 ID，如 json 而非 JSON。

说起 VS Code 里的 Markdown 预览，markdown.preview.autoRefresh 这个设置挺有意思。从 1.80 版本开始，它默认就是开启的，但每次软件升级或者重装之后，这个开关常常会被重置回默认状态。所以，很多人抱怨预览不实时，问题往往就出在这里——你以为它开着，其实它已经悄悄关上了。

预览不自动刷新？先查这两个设置

首先得明确一点，VS Code 内置的预览功能，跟 Typora 那种所见即所得的实时编辑体验不同，它做不到毫秒级的响应。但是，“保存即刷新”应该是最基本的体验底线。如果你发现修改了文字，必须手动点击刷新按钮预览才会更新，那大概率是下面这两个核心设置没配对：

• markdown.preview.autoRefresh：这个开关控制着「编辑时是否自动刷新预览」，必须设置为 true。
• markdown.preview.refreshOnSa ve：这个则控制「保存文件后是否强制刷新预览」，也建议设为 true。尤其是在远程开发环境，或者文件监听功能偶尔失灵的时候，它能起到关键的兜底作用。

解决方法很简单：打开设置（快捷键 Ctrl+,），搜索这两个选项，确保它们都被勾选。不过，这里有个常见的“坑”：如果你安装了像 Markdown All in One 这样的第三方扩展，它可能会接管预览行为。这时候，真正起作用的配置项就变成了 markdown.extension.preview.autoUpdate，而不是 VS Code 原生的那个了。检查的时候，别忘了这一点。

数学公式渲染失败？KaTeX 启用 + 空行 + 正确语法

数学公式渲染失败，大概是 Markdown 写作中最让人头疼的问题之一。明明写了 $$E = mc^2$$，预览却还是原封不动的代码文本，这通常不是因为没装插件，而是 VS Code 内置的 KaTeX 渲染引擎压根就没被激活。

• 核心开关在 settings.json 里：你需要手动添加一行配置："markdown.math.enabled": true（请注意，这个功能在 VS Code 1.84 及以上版本才被支持）。
• 格式规范是关键：公式块（用双美元符包裹的部分）前后必须各有一个空行，否则解析器会直接跳过它。比如：

  $$\int_0^1 x^2 dx$$

  它的上下都不能紧贴着其他文字。
• 语法别用混：行内公式用单美元符，例如 $E = mc^2$；块级公式用双美元符，例如 $$...$$。务必避免混用中文符号或者误用反引号。
• 还有一个隐藏陷阱：如果你同时开启了 markdown.extension.math.inlineEnabled 这个扩展设置，可能会导致单美元符的行内公式被错误地解析成块级公式，从而引发渲染崩溃。所以，这个选项通常建议保持禁用。

代码块高亮失效？语言 ID 必须严格匹配

代码块没有高亮，只剩下灰底白字？这十有八九是语言标识符（Language ID）写错了。VS Code 依赖 TextMate 语法包来着色，它对语言 ID 的匹配要求非常严格，拼错一个字母就会失效。

• 记住正确的写法：```json、```typescript、```bash、```html（注意，是 html 全小写，而不是 HTML 或 JS）。
• 如果不确定当前代码块被识别成什么语言，可以按 Ctrl+Shift+P 打开命令面板，运行 Developer: Inspect Editor Tokens and Scopes，然后把光标放到代码块里，查看「language」字段的值。
• 这里列举几个前端开发常用的标准语言 ID：html / css / ja vascript / typescript / json / markdown。规则就是：全小写，无空格，不带版本号。

滚动不同步、中文乱码、导出失败？三个关键开关

编辑区和预览窗格滚动不同步、中文标题显示异常、导出 PDF 时图片变成红叉……这些看似不相关的问题，背后往往指向同一组底层配置。

• 滚动同步问题：markdown.preview.scrollEditorWithPreview 和 markdown.preview.scrollPreviewWithEditor 这两个设置必须同时设为 true，缺一不可。
• 脚本与样式支持：markdown.preview.enableScripts 必须设置为 true。否则，Mermaid 图表、KaTeX 公式以及任何自定义 CSS 样式都会被安全沙盒拦截而无法加载（当然，这个设置建议仅在编辑本地可信文档时开启）。
• 导出功能须知：导出 PDF 或 HTML 并非 VS Code 的内置功能，通常需要借助 Markdown Preview Enhanced 这类扩展，通过右键菜单调用。另外，导出时图片路径必须使用相对路径（例如 ./img/chart.png），如果使用绝对路径或网络地址，导出引擎很可能会拒绝加载，导致图片缺失。

最后提一个最容易被忽略的细节：编辑器和预览的同步滚动功能，仅在「侧边预览」（通过 Open Preview to the Side 命令打开）模式下生效。如果是全屏预览或者弹出窗口预览，则不支持锚点联动。