VSCode原生不支持自定义TODO注释的悬停提示,因其不属于语言语义范畴;所有TODO悬停效果均依赖第三方扩展模拟,真hover需开发语言服务器实现textDocument/hover响应。

VSCode 本身不支持直接自定义悬停(Hover)里的 TODO 任务信息
悬停提示(hover)由语言服务器(LSP)或语法高亮引擎控制,而原生的 TODO 注释不属于语言语义范畴——它只是普通注释文本。VSCode 不会把 // TODO: 当作可解析的结构化数据,因此不会在 hover 中展示额外内容。你看到的任何“TODO 悬停信息”,基本都来自第三方扩展的模拟行为(比如用装饰器伪造 tooltip),而非真正的 LSP textDocument/hover 响应。
Todo Tree 和 TODO Highlight 都不提供 hover 内容,只做扫描和高亮
这两个主流插件的工作机制是:
- 用
ripgrep或 VSCode 的文本搜索 API 扫描文件 - 匹配正则后生成侧边栏列表或行内背景色
- 完全不介入
hover请求流程,也不返回 Markdown 内容给编辑器的悬浮层
所以即使你配了 "TODO": { "color": "#ff8c00" },鼠标悬停依然只显示原始注释行(如 // TODO: 修复空指针),不会加图标、优先级、作者名或上下文链接。
真要实现自定义 hover,得靠语言服务器扩展开发
这是唯一能控制 hover 显示内容的路径,但门槛高、维护成本大:
- 必须实现一个 Language Server,监听
textDocument/hover请求 - 在响应中返回
{ contents: { kind: 'markdown', value: '### REVIEW\n- by @alice\n- 2026-10-19' } }这类结构 - 需手动识别
// REVIEW(...):等模式,提取括号内用户名、日期等字段 - 要处理多语言(
javascript、typescript、python)的注释语法边界,避免误匹配字符串里的TODO
示例片段(在 server 中):
connection.onHover((params) => {
const line = document.getText().split('\n')[params.position.line];
const match = line.match(/\/\/\s+(REVIEW)\(([^)]+)\):\s+(.*)/);
if (match) {
return {
contents: {
kind: 'markdown',
value: `### ${match[1]}\n- by ${match[2]}\n- ${new Date().toISOString().slice(0, 10)}\n\n${match[3]}`
}
};
}
});
更现实的替代方案:用 JSDoc/Docstring + 类型标注“伪装”TODO
如果你只需要在关键函数或配置项上附带可 hover 的待办说明,可以绕过注释限制,改用语言原生支持的文档机制:
- 在 TypeScript 中写:
/** @todo Refactor this to use Zod schema */ export function validate() { ... } - 在 Python 中写:
def fetch_data():\n """@todo Add retry logic on 5xx errors""" - 配合
Pylance或TypeScript Server,这些会被正常解析进 hover - 缺点:不能放在任意代码行,只能依附于声明节点(函数、类、变量)
真正自由地在任意位置显示结构化 hover 信息,目前没有零配置、免开发的方案。别被“TODO 悬停”这个词误导——它本质上是个伪需求,实际要的往往是“快速跳转 + 上下文感知 + 可归档”,而这些 Todo Tree 已经做得足够好。


















