hover 不生效主因是 languageid 不匹配；需用开发者工具查真实 languageid，确保与 activationevents 和 registerhoverprovider 一致；markdownstring 需转义且禁用 html；providehover 必须异步避免卡顿。
Hover 不生效，90% 是 documentSelector 和实际文件的 languageId 对不上。不是代码写得不对，是 VSCode 根本没把你的 provider 绑到当前文件上。
怎么确认当前文件真实的 languageId？
别猜，也别看文件后缀。打开命令面板（Ctrl+Shift+P），执行 Developer: Toggle Developer Tools，在 Console 里输入：
vscode.window.activeTextEditor?.document.languageId
回车就能看到真实值。常见坑：
-
.ts文件返回typescript，不是javascript -
.vue单文件组件默认是vue，但带<script setup></script>的可能被识别为vue-html或typescript -
.jsonc是jsonc，不是json
这个值必须和 package.json 里的 activationEvents（如 onLanguage:typescript）以及 registerHoverProvider() 的第一个参数完全一致。
provideHover 返回空或格式错乱？检查 Markdown 转义
vscode.Hover 接收的是 MarkdownString，它不渲染任意 HTML，只认有限内联语法（**bold**、`code`、[link](url)）。所有 _、*、` 都要转义，否则整个内容变空白。
- 用
new vscode.MarkdownString(text, true)，第二个参数true启用自动转义 - 避免多行代码块
```：Hover 渲染器不支持，改用单行`const x = 1` - 链接只能是绝对 URL 或
command:协议，./readme.md无效 - 图片不能用
file://，也不推荐 base64；可用https://或vscode-resource:（已弃用，慎用）
悬停卡顿或根本没反应？别在 provideHover 里做同步操作
provideHover 是同步函数签名，但 VSCode 允许你返回 Thenable<hover></hover>。如果你在里面调 fs.readFileSync、遍历大数组、或等网络请求，会直接卡死悬停体验，甚至超时丢弃。
- 所有 I/O 必须异步：
fs.promises.readFile+await，然后return Promise.resolve(hover) - 高频查询结果建议缓存，比如用
Map键为document.uri.toString() + position.line - 加兜底超时：
Promise.race([fetchData(), new Promise(r => setTimeout(r, 300))])
真正难的不是写逻辑，而是把「想查什么」和「怎么快查」拆开——前者决定信息是否准确，后者决定用户愿不愿意继续用你的插件。
