必须显式调用 vscode.languages.registerHoverProvider() 注册 hover 提供者，需匹配 languageId、正确构造 vscode.Hover 返回值、避开同步 I/O 和 Markdown 渲染陷阱，并确认编辑器语言模式与设置启用状态。
VSCode扩展中怎么注册自定义 hover 提示
必须显式调用 vscode.languages.registerHoverProvider()，否则你的 hover 逻辑不会被触发。这不是“开个开关”就能生效的功能，而是需要匹配语言 ID、正确构造返回内容、避开常见注册陷阱。
实操建议：
- 确认当前文件真实
languageId：按Ctrl+Shift+P→ 输入Developer: Toggle Developer Tools→ 在 Console 里执行vscode.window.activeTextEditor?.document.languageId，别凭经验写js或py -
package.json的activationEvents和contributes.languages必须包含对应 languageId，比如"onLanguage:typescript"和{"id": "typescript"} - 注册时的
documentSelector要精确，推荐用数组形式：[{ language: 'typescript' }]，而不是模糊的{ scheme: 'file' } - 返回的
vscode.Hover内容必须是vscode.MarkdownString或vscode.MarkedString[]，不能直接返回纯字符串
hover 内容为空或格式错乱？检查 Markdown 转义和渲染限制
Hover 面板只支持有限的内联 Markdown，且所有特殊字符（_、*、`）若未转义，会导致整个提示空白——不是崩溃，是静默失败。
实操建议：
- 用
new vscode.MarkdownString(text, true)构造，第二个参数true启用自动转义，省去手动\*处理 - 避免多行代码块
```：Hover 渲染器对它支持极差，改用单行`const x = 1`或关键词高亮 - 链接只能是
https://或command:协议，./readme.md或file://全部无效 - 图片不支持本地路径；
vscode-resource:已弃用，base64 内联体积大、加载慢，慎用
hover 响应卡顿或超时？别在 provideHover 里做同步耗时操作
provideHover 是同步函数签名，但 VSCode 允许你返回 Thenable。如果你在里面读文件、调 HTTP、遍历 AST，就会卡住整个悬停面板，用户看到的是“空白一闪”或 2 秒无响应。
实操建议：
- 所有 I/O 操作必须异步：用
fs.promises.readFile替代fs.readFileSync，并return Promise.resolve(hover) - 高频查询结果务必缓存，比如按
document.uri.toString() + position.line为 key 存进Map - 加兜底超时：
Promise.race([fetchHover(), new Promise(r => setTimeout(r, 800))])，避免 LSP 挂起拖垮体验 - 不要在
provideHover中启动新进程或等待外部服务就绪——hover 不是初始化入口
为什么改了代码 hover 还不显示？优先排查 languageId 和启用状态
最常被忽略的两个点：一是你注册的 languageId 和实际打开的文件不一致（比如 .ts 文件的 languageId 是 typescript，不是 javascript），二是 hover 功能本身被关了，或者被其他扩展劫持。
实操建议：
- 右下角状态栏看语言模式是否为预期值（如
TypeScript），不是Plain Text - 检查设置中
editor.hover.enabled是否为true；设成false后Ctrl+K Ctrl+I仍可用，但自动悬停消失 - 临时禁用 Copilot、Sesame AI 等 AI 插件——它们常静默覆盖原生 hover，且不报任何错误
- 打开 DevTools Console，悬停时观察是否有
HoverProvider not found或Cannot read property 'provideHover' of undefined类报错
修改完代码后，hover 提示不会自动刷新——哪怕你只是改了一个标点。必须保存文件，语言服务器才会重新解析 AST 并更新缓存。这个“保存即生效”的隐式依赖，比配置项更容易被忽略。
