VS Code 中 Markdown 预览不实时刷新怎么办？

Question

在 VS Code 中编辑 Markdown 文件时，预览窗口（Ctrl+Shift+V 或右键 → “Open Preview”）常出现**修改后不自动刷新**的问题：保存文件后预览内容仍为旧版本，需手动关闭再重开预览或强制刷新（Ctrl+R），严重影响写作效率。该问题多见于启用“自动保存”但未触发预览更新、插件冲突（如某些 Markdown 扩展覆盖默认预览逻辑）、工作区启用了“Files: Auto Save”但设置为 `afterDelay` 且延迟过长，或预览窗口被意外固定（Pinned）导致缓存锁定。此外，VS Code 1.85+ 版本中，若开启 `markdown.preview.autoShowPreviewToSide` 并同时打开多个预览标签，也可能因资源复用导致状态不同步。排查建议：禁用第三方 Markdown 插件、检查 `markdown.preview.refreshOnSave` 是否为 `true`（默认开启）、确认文件未被外部程序独占写入，并尝试重置预览会话（关闭所有预览后重新触发）。

Answer 1

```html

一、现象层：确认预览不刷新的典型行为模式

• 按下 Ctrl+Shift+V 或右键 → “Open Preview” 后，预览窗口首次渲染正常；
• 编辑 Markdown 内容后执行 Ctrl+S（手动保存），预览内容未变化；
• 启用 Files: Auto Save（设为 afterDelay 或 onFocusChange）时，延迟期过后仍无刷新；
• 关闭并重开预览标签页，或按 Ctrl+R 强制重载，内容立即更新——说明底层渲染引擎工作正常。

二、配置层：核心设置项校验与修正

VS Code 内置 Markdown 预览依赖以下关键设置（可通过 settings.json 或 GUI 搜索验证）：

设置项	推荐值	影响说明
markdown.preview.refreshOnSave	true（默认）	控制「保存即刷新」是否启用；若为 false，则必现不刷新
markdown.preview.autoShowPreviewToSide	false（建议临时禁用）	VS Code ≥1.85 中开启后多标签复用同一 WebView 实例，易引发状态错位

三、环境层：插件冲突与生命周期干扰分析

第三方 Markdown 插件（如 Markdown All in One、Markdown Preview Enhanced）常劫持预览入口。执行以下诊断流程：

1. 进入命令面板（Ctrl+Shift+P），运行 Developer: Toggle Developer Tools；
2. 切换至 Console 标签，输入 vscode.workspace.getConfiguration('markdown').preview 查看当前生效配置源（user/workspace/extension）；
3. 若发现 extension 优先级高于 built-in，说明某插件已覆盖默认预览逻辑。

四、系统层：文件句柄与缓存锁定深度排查

当预览不刷新且配置无误时，需排除操作系统级干扰：

• 检查文件是否被其他进程独占打开（如：Word、Obsidian、Git LFS 锁定、Windows 资源管理器预览窗格）；
• 在终端执行 lsof -i | grep <your-file.md>（macOS/Linux）或 handle.exe -a <file-path>（Windows Sysinternals）；
• VS Code 缓存路径：$HOME/.vscode/Cache 或 %APPDATA%\Code\Cache，可尝试清空 WebView 相关子目录。

五、架构层：VS Code 1.85+ 预览引擎变更与应对策略

自 VS Code 1.85 起，Markdown 预览采用基于 Webview2（Electron 25+）的沙箱化渲染器，引入资源复用机制。其刷新触发链如下：

File System Event → Editor TextModel Change → Save Event → markdown.preview.refreshOnSave === true → WebView.postMessage('refresh')

但若存在以下情形，该链将中断：

• 多个预览标签共享同一 WebView 实例（由 autoShowPreviewToSide + 多次 Ctrl+Shift+V 触发）；
• WebView 内部 JS 执行异常（开发者工具 Console 中可见 Failed to execute 'postMessage' on 'Window'）；
• 工作区启用了 "files.watcherExclude" 且误配了 **/*.md，导致 FS 事件丢失。

六、实战修复矩阵：按优先级排序的解决方案

graph TD
  A[预览不刷新] --> B{是否多标签共用预览？}
  B -->|是| C[关闭所有预览 → 右键单文件 → Open Preview to the Side]
  B -->|否| D{是否启用第三方 Markdown 插件？}
  D -->|是| E[禁用全部 → 重启 VS Code → 单独启用内置预览]
  D -->|否| F{检查 refreshOnSave 是否为 true？}
  F -->|否| G[手动设为 true 并保存 settings.json]
  F -->|是| H[清空 Cache + 检查文件句柄]

七、长效治理建议：面向工程团队的标准化配置模板

在团队 .vscode/settings.json 中强制统一关键项（避免个人配置漂移）：

{
  "markdown.preview.refreshOnSave": true,
  "markdown.preview.autoShowPreviewToSide": false,
  "files.autoSave": "off",
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/node_modules/**": true
  }
}

配合 ESLint-style 的 markdownlint 预提交钩子，确保文档可维护性与预览一致性同步演进。

```