必须同时启用markdown.preview.scrollEditorWithPreview和markdown.preview.scrollPreviewWithEditor才能实现双向滚动同步，单开一个无效；预览窗口右上角需出现双向箭头图标，且文件须已保存、路径不含未编码的中文或空格。
预览窗口不随编辑光标滚动？检查 scrollSync 是否启用
VSCode 的 Markdown 预览默认不会自动跟随编辑器光标位置跳转，这是最常被误认为“失效”的点。核心开关是 markdown-preview-enhanced.scrollSync，它控制编辑器与预览之间的双向滚动联动。
- 必须设为
true，仅开启autoPreview不够 - 该选项对「光标所在段落」生效，不是像素级定位——比如光标在标题下第三行，预览会滚动到该标题区块起始处，而非精确到第三行渲染位置
- 若文档含大量数学公式或 Mermaid 图表，首次同步可能延迟 200–400ms，属正常行为，无需调高 debounce 值
scrollSync 失效的三大真实原因
即使配置正确，仍可能不同步。常见触发条件如下：
- 编辑器当前处于「列选择模式」（
Alt+拖拽后未退出），此时光标逻辑被临时覆盖，滚动同步暂停 - 预览窗口被手动拖动过（哪怕只滑了一点），VSCode 会暂时锁定同步，需再次点击编辑器任意位置重置
- 文件路径含中文或空格且未用引号包裹时，某些旧版插件会解析失败，表现为预览空白 + 同步中断；建议统一用英文路径或 URL 编码处理
右侧预览布局下，光标跳转偏移量怎么调？
启用 previewOnRightSide 后，部分用户发现预览滚动位置比预期“高半屏”。这不是 bug，而是由行高（lineHeight）与字体度量差异导致的视觉错位。
- 预览渲染使用浏览器原生排版，而编辑器使用 Canvas 渲染，两者对
lineHeight: 1.6的实际像素计算存在 ±2px 偏差 - 解决方法：微调
markdown-preview-enhanced.lineHeight，例如从1.6改为1.58或1.62，观察预览锚点是否更贴合 - 不推荐修改
fontSize来补偿——这会同时影响阅读体验，属于治标不治本
多光标编辑时，预览还同步吗？
同步逻辑只响应「主光标」（即最后激活的那个光标）的位置，其余多光标位置不参与滚动计算。
- 当你用
Ctrl+D选中多个user.name并开始输入时，预览只会跳转到第一个匹配项所在的段落 - 若用
Alt+Click在分散位置加了 5 个光标，只有最后一个点击位置会触发预览滚动 - 想强制刷新预览到当前视口，按
Ctrl+Shift+P→ 输入Markdown Preview Enhanced: Refresh Preview手动触发一次
复杂点在于：滚动同步本质是「段落级映射」，不是「光标级映射」。它依赖 HTML 标签结构（如 、）做锚点定位，一旦 Markdown 中混用 HTML 块或自定义指令（如 %%include%%），锚点可能丢失或错位。这种情况下，别硬调参数，优先检查源码结构是否规整。
