Hover 不生效的主因是 documentSelector 与 languageId 不匹配，需确认文件真实 languageId、保持 package.json 配置一致、注册时使用精确匹配的 selector，并注意 Markdown 转义、异步操作及调试日志。
Hover 提示没反应？检查 languageId 和 documentSelector 配置是否匹配
VSCode 的 Hover 功能不会自动触发，必须显式注册对应语言的 documentSelector。常见错误是插件声明支持 "javascript"，但实际打开的是 .ts 文件——TypeScript 文件的默认 languageId 是 "typescript"，不是 "javascript"。
实操建议：
- 用
editor.languageId命令（Ctrl+Shift+P → “Developer: Toggle Developer Tools” → Console 输入vscode.window.activeTextEditor?.document.languageId）确认当前文件真实 languageId -
package.json中contributes.languages列表要和activationEvents里的onLanguage:xxx一致 - 注册 Hover provider 时，
vscode.languages.registerHoverProvider()的第一个参数必须是匹配的documentSelector，例如[{ language: 'typescript' }]或{ scheme: 'file', language: 'json' }
Hover 内容显示为空或格式错乱？注意 Markdown 字符转义和行内样式限制
Hover 返回的 MarkdownString 不支持任意 HTML，仅支持有限的内联 Markdown（如 **bold**、`code`、[link](...)），且所有反引号、星号、下划线需手动转义，否则解析失败导致空白。
实操建议：
- 用
new vscode.MarkdownString(text, true)构造时传true启用严格转义（自动处理_、*、`等） - 避免在 Hover 中嵌入长代码块：多行
```在 Hover 中渲染异常，改用单行`inline code`或精简为关键词高亮 - 链接必须是绝对 URL 或
command:协议，相对路径（如./readme.md）无效 - 图片不支持本地
file://路径，只能用网络 URL 或vscode-resource:（已弃用）或 base64 内联（不推荐）
Hover 触发位置不准或延迟高？别在 provideHover 里做同步耗时操作
provideHover 是同步函数，但 VSCode 允许返回 Thenable<Hover>。若你在其中读文件、调外部 API 或遍历大数组，会导致悬停卡顿甚至超时无响应。
实操建议：
- 所有 I/O 操作必须异步：用
fs.promises.readFile替代fs.readFileSync，并返回Promise.resolve(hover) - 缓存高频查询结果（如 AST 节点信息），用
Map按document.uri.toString() + position.line做键，避免重复解析 - 设置超时兜底：
Promise.race([fetchData(), new Promise(r => setTimeout(() => r(null), 300))])，防止网络请求拖垮体验 - 不要在
provideHover中调用vscode.window.showInformationMessage等 UI 弹窗——会阻塞主线程且违反 Hover 设计契约
调试 Hover 不生效？启用 trace 和日志定位拦截点
VSCode 不报错也不显示 Hover，往往是因为 provider 注册失败、selector 不匹配，或被其他插件覆盖。靠猜效率极低。
实操建议：
- 在
activate()开头加console.log('Hover provider registered')，再打开开发者工具（Ctrl+Shift+P → “Developer: Toggle Developer Tools”）看控制台是否有输出 - 在
provideHover函数第一行加console.log('provideHover called at', position)，确认是否被调用 - 启动插件时加
--log-level=trace参数（终端运行code --extensionDevelopmentPath=/path/to/your/ext --log-level=trace），搜索日志中hover或registerHoverProvider - 禁用其他插件（尤其是 Prettier、ESLint、TypeScript 插件），排除 provider 被优先级更高者拦截的可能
Hover 表面简单，但 languageId 匹配、Markdown 安全性、异步边界和调试链路这四点，任一疏漏都会导致“写了却看不到”。最常被忽略的是 documentSelector 的精确性——它不是模糊匹配，而是严格按字符串比对，连大小写都敏感。
