VSCode悬停不显示图片或公式是因为原生不解析Markdown链接和LaTeX，需插件注入HoverProvider；须确认languageId为markdown、用Image Preview插件或自定义provider，并避免同步阻塞、路径错误及插件冲突。
为什么悬停时图片不显示，只看到路径文本
VSCode 原生不解析图片链接或 Markdown 公式为可视内容，必须靠插件注入 hover 内容。常见错误是直接在 JS/TS 文件里写  或 $$E=mc^2$$，但没启用对应 hover provider——此时悬停只会显示原始字符串，甚至根本无响应。
实操建议：
- 确认当前文件 languageId 正确：比如 Markdown 文件的
languageId是markdown，不是plaintext或md；可在命令面板运行editor.languageId验证 - 安装并启用
Image Preview插件（非官方但稳定）或自己注册HoverProvider时指定{ language: 'markdown' } - 图片路径必须可被 VSCode 解析为绝对 URI：相对路径如
./assets/logo.png需在 workspace 根目录下才有效；https://链接默认支持，无需额外处理 - 正则匹配要覆盖常见格式：
!\[.*?\]\((.+?)\)（Markdown 图片）、src=["']([^"']+)["']（HTML img）、url\(([^)]+)\)（CSS）
MathJax 公式在 hover 中渲染失败的典型原因
即使 Markdown 预览能正常显示公式，悬停时仍可能只显示 LaTeX 源码——因为 HoverProvider 返回的 MarkdownString 不自动触发 MathJax 渲染，且 VSCode 的 hover 区域对数学引擎支持极弱。
实操建议：
- 不要指望在 hover 里直接渲染
$$...$$：VSCode hover 不执行 MathJax/KaTeX 初始化，返回的$$E=mc^2$$就是纯文本 - 若真需公式提示，改用内联代码块 + 注释说明：
new vscode.MarkdownString(`**公式含义**：质能等价，其中 $E$ 为能量，$m$ 为质量`)，保留$符号但不依赖渲染 - 更可靠的做法是跳转到预览：在
provideHover中返回带command:链接的 Markdown，例如[查看完整公式](command:markdown.showPreview)，点击后打开右侧预览窗 - 禁用所有干扰插件（尤其是 Copilot、CodeGeeX）再测试，它们常劫持 hover 并丢弃数学相关字段
自定义 hover 显示图片的最小可行代码
不需要复杂扩展，几行代码就能让 Markdown 文件中悬停图片路径时弹出缩略图。关键不是“怎么写”，而是“在哪注册”和“怎么构造安全内容”。
实操建议：
- 在
package.json的activationEvents中声明onLanguage:markdown，并在contributes.languages中注册markdown -
provideHover函数内用document.lineAt(position.line).text获取整行，再用正则提取图片 URL - 构造
vscode.Hover时，图片必须转为 base64 或网络 URL：vscode.Uri.file(path).with({ scheme: 'vscode-resource' })已弃用，改用vscode.Uri.parse('data:image/png;base64,...')（仅小图）或直接用https://链接 - 务必加 try/catch：路径不存在、跨域、404 都会导致
provideHover报错，整个 hover 失效
hover 提示卡顿或延迟高，其实是同步阻塞了
很多人把读文件、发 HTTP 请求、解析大 JSON 放进 provideHover，结果悬停像卡死——这不是性能问题，是 VSCode 明确要求 hover 必须快速返回，超时（约 500ms）就丢弃响应。
实操建议：
-
provideHover必须返回Thenable，不能是同步值；哪怕只是Promise.resolve(hover)也能避免主线程阻塞 - 本地图片预览不要实时读取文件：提前缓存
Map存 base64，键为document.uri.toString() + ':' + line - 网络图片加超时：
Promise.race([fetch(url).then(r => r.arrayBuffer()), new Promise(r => setTimeout(r, 800))]) - hover 内容不会随文件修改自动更新：改了图片路径或公式后，必须保存文件，VSCode 才会重新调用
provideHover
真正难的不是写代码，是让 hover 在各种 languageId、路径格式、插件共存环境下稳定触发。多数人卡在第一步：没确认当前文件的 languageId 就瞎配 documentSelector。
