简介面向VS Code插件开发者的实战资源系统讲解跳转到定义、自动补全、悬停提示三大核心能力的实现路径。内容以vscode.languages命名空间下的Provider机制为主线逐一解读registerDefinitionProvider、registerCompletionItemProvider、registerHoverProvider的注册方式、参数含义与返回值构造并结合package.json依赖包跳转、this.dependencies.xxx自动补全等贴近真实场景的示例代码演示Location、CompletionItem、Hover等对象的创建与使用同时点明高亮范围控制、activationEvents触发配置等易错细节。资源打包为1个PDF文件大小248KB结构紧凑适合快速通读或在插件开发时按需查阅PDF从注册Provider到返回定位、补全与悬停内容步骤环环相扣代码片段可直接迁移到自己的插件项目中。已有45553人学习下载尤其适合编写自定义语言服务、开发效率工具以及希望系统掌握VS Code插件机制的中高级前端开发者。1. 有人问我 VSCode 插件开发先学什么我永远先说跳转到定义、自动补全、悬停提示我第一次写 VSCode 插件开发时满脑子想的是侧边栏、状态栏、Webview 面板觉得这些才叫“做产品”。结果被同组做基础工具的同行问了一句“你这插件能把我的 F12 用起来吗”当场答不上来。后来想明白了VSCode 插件开发里真正决定实用性的不是界面而是跳转到定义、自动补全、悬停提示这三个能力。你把光标放到一个符号上能否按 F12 跳到定义输入到一半是否自动给出候选鼠标悬停是否有一句话说明来源——这三件事才是用户每天按几十次的路径。这一篇就是把这三个能力一次讲透的落地笔记。它不会停在 API 罗列而是把 Provider 的注册与返回类型、参数怎么设、哪些位置容易踩坑全按可复现的方式给你。新手照着最小命令能跑起来熟手可以直接跳到第 5 章的排查实录对照自己的实现。2. 先给机制定位激活事件、DocumentSelector 与三个 Provider 的注册关系这三个功能虽然入口不同但底层是同一套契约在package.json里声明语言在activate里注册 ProviderProvider 返回特定结构VSCode 负责把结果渲染成跳转、候选列表或悬停卡片。把这套契约搞清楚后面三分之二的坑都能提前避掉。2.1 用 onLanguage 而不是*来激活激活时机决定了首屏体验很多插件模板图省事直接在package.json里写activationEvents: [*]结果插件在 VSCode 启动时就全部加载。对于一个只处理.mylang文件的插件这是巨大的浪费用户打开编辑器会明显感觉卡顿。我一般会把激活事件收敛到语言维度{ activationEvents: [ onLanguage:mylang ], contributes: { languages: [ { id: mylang, extensions: [.mylang, .myl] } ] } }逻辑说明onLanguage:mylang表示只有用户打开这种语言的文件时插件才启动。只要contributes.languages里声明了idVSCode 会自动补一条隐式激活事件但显式写出来更直观后续要加onCommand、onStartupFinished时也能一眼看清。参数说明id必须与代码里DocumentSelector的language保持一致extensions数组里是关联的文件后缀。不建议用*也不建议把所有功能都挂在onStartupFinished上那会牺牲按需加载的优势。2.2 一个文件里注册三个 Provider最小可用骨架下面这段骨架代码可以放进extension.ts直接跑。它把跳转、补全、悬停三个注册都做了只是返回空值目的是先验证注册链路是通的。import * as vscode from vscode; export function activate(context: vscode.ExtensionContext) { const selector: vscode.DocumentSelector { language: mylang, scheme: file }; const defProvider vscode.languages.registerDefinitionProvider(selector, { provideDefinition(document, position) { return null; // 还没实现先不拦路 } }); const compProvider vscode.languages.registerCompletionItemProvider(selector, { provideCompletionItems(document, position) { return []; // 空数组表示没有候选 } }, .); // 第三个参数是触发字符按点号时自动弹出补全 const hoverProvider vscode.languages.registerHoverProvider(selector, { provideHover(document, position) { return null; // null 表示不处理交给其他插件 } }); context.subscriptions.push(defProvider, compProvider, hoverProvider); }逻辑说明三个 Provider 共用同一个selector它决定了这些能力只在.mylang文件里生效。context.subscriptions.push是标准收尾插件卸载时这些注册会被自动清理。参数说明scheme: file值得写清楚。如果插件面向本地文件加上scheme: file可以避免在“未保存的临时文档”或“预览文档”里误触发如果还要支持 Git 差异视图就得改成scheme: file, untitled, git或直接用语言匹配。2.3 返回类型决定交互Location、CompletionList 和 Hover 的契约三个 Provider 的返回值直接影响 VSCode 的交互形式我整理成一张对照表Provider接口方法空返回值行为异常行为DefinitionProviderprovideDefinition继续匹配其他插件该提供者被禁用CompletionItemProviderprovideCompletionItems无候选退回内置词该提供者被禁用HoverProviderprovideHover无悬停内容该提供者被禁用参数说明三个方法都可以返回null表示“我不处理”。但如果你抛出异常VSCode 会把当前 Provider 标记为异常状态后续调用全部失效。所以我在实现里会用 try/catch 包一层记录日志后返回null而不是让异常冒泡。这里的核心思维是Provider 只是“提供内容”渲染和交互是 VSCode 的职责。你返回LocationVSCode 画跳转箭头和预览框你返回CompletionItem[]它做候选排序和筛选你返回Hover它渲染悬停卡片。理解了这层边界就不会把 UI 逻辑写进插件里。3. 跳到定义从最小返回 Location 到跨文件符号定位跳转到定义是三个能力里最重的因为用户对 VSCode 的预期已经被 C/C 和 TypeScript 拉到很高F12 要准、要快、要能跨文件。我们自己实现的语言插件水准线可以不用追平大型语言服务器但至少要做到“按 F12 不落空”。3.1 三种返回值的差异Location、LocationLink 与多定义位置跳转 Provider 的返回值最常见的写法是new vscode.Location(uri, range)。uri是目标文件的资源标识range是定义位置的行列范围。一个Location就够用但有几个边界你要提前知道。第一返回数组时VSCode 会打开 Peek 面板让你选择。常用于“多个文件里都有同名定义”的场景。注意数组非空时 VSCode 不会直接跳转而是先展示选择列表如果你的插件永远只返回一个结果返回单个Location体验最顺。第二LocationLink提供更精细的控制包含originSelectionRange、targetUri、targetRange、targetSelectionRange。用它的好处是预览框里高亮的范围可以精确到标识符而不是整行。多文件选择场景下我通常优先返回LocationLink[]。第三range本身要精确定位到定义符号上。最常见的坑是只给行号不给列导致跳过去后光标落在行首而不是落在def foo的foo上。这个后面排查实录里细说。3.2 最小可用的 DefinitionProvider在当前文件里定位定义先从单文件场景入手。假设我们的.mylang文件里定义语句长这样def foo: return 1那最小实现就是遍历所有行找def 标识符行返回一个LocationprovideDefinition(document, position) { const wordRange document.getWordRangeAtPosition(position); if (!wordRange) return null; const word document.getText(wordRange); const pattern /^def\s([A-Za-z_]\w*)/; for (let i 0; i document.lineCount; i) { const line document.lineAt(i).text; const match line.match(pattern); if (match match[1] word) { const startPos new vscode.Position(i, match.index 4); const endPos startPos.translate(0, word.length); return new vscode.Location(document.uri, new vscode.Range(startPos, endPos)); } } return null; }逻辑说明getWordRangeAtPosition先拿到光标下的单词及其范围document.getText(wordRange)提取出单词本身。正则^def\s匹配定义行match.index 4是跳过def前缀后的起始列。参数说明这里的 4 是指def加一个空格的长度如果定义语法改成define或fn这个偏移量必须同步改否则跳转位置会错。更稳的做法是用line.indexOf(match[1])来定位避免硬编码前缀长度。如果你的标识符包含中文或连字符getWordRangeAtPosition默认的单词规则会失效可以传入第二个参数自定义正则const wordRange document.getWordRangeAtPosition( position, /[\w\u4e00-\u9fa5-]/ );3.3 跨文件跳转findFiles 建索引并缓存到内存单文件跳转太局限真实场景里定义往往分散在多个文件。一个可靠做法是插件激活时扫描一次工作区把符号建立索引之后每次跳转都只查内存中的 Map。class DefIndex { private cache new Mapstring, vscode.Location[](); async build(): Promisevoid { const uris await vscode.workspace.findFiles(**/*.defs); for (const uri of uris) { const doc await vscode.workspace.openTextDocument(uri); const text doc.getText(); const pattern /^def\s([A-Za-z_]\w*)/gm; let match: RegExpExecArray | null; while ((match pattern.exec(text))) { const name match[1]; const startPos doc.positionAt(match.index 4); const endPos startPos.translate(0, name.length); const loc new vscode.Location(uri, new vscode.Range(startPos, endPos)); const list this.cache.get(name) || []; list.push(loc); this.cache.set(name, list); } } } get(name: string): vscode.Location[] { return this.cache.get(name) || []; } }逻辑说明findFiles(**/*.defs)只匹配扩展名为.defs的文件避免把源码目录里的无用文件也扫进来。openTextDocument只是读取内容不会弹出编辑器窗口。positionAt会把字符偏移量换算成行列位置这是和前面手工计算列号完全不同的思路更不容易出错。参数说明findFiles的 glob 默认不会遍历node_modules和隐藏目录这对插件来说通常是好事。如果你确实要包含需要传findFiles(include, exclude, maxResults)第二个参数写**/{node_modules,.git}/**来覆盖默认排除。缓存建立之后别忘了在文件保存时做失效处理避免用户改了定义文件但跳转还指向旧行vscode.workspace.onDidSaveTextDocument((doc) { if (doc.languageId mylang || doc.uri.path.endsWith(.defs)) { index.build(); // 或者只重建这一个文件对应的符号量小就全量重建 } });4. 自动补全CompletionItem 字段、触发字符与排序的完整取舍自动补全是用户感知最强的能力因为你每敲一个字符候选列表就贴在你光标下方。做得粗糙和做得细腻的区别全在字段设置上。4.1 CompletionItem 里要调的字段label、kind、insertText、sortText先看一个能直接运行的补全提供者provideCompletionItems(document, position) { const keywords [if, repeat, done, else]; return keywords.map(name { const item new vscode.CompletionItem(name, vscode.CompletionItemKind.Keyword); item.detail mylang 关键字; item.documentation new vscode.MarkdownString(**${name}** 是保留关键字); item.insertText name ; item.sortText 0 name; return item; }); }逻辑说明label是候选列表里展示的文字也是默认的插入文本kind决定左侧图标和右侧的分类标签insertText如果不设置VSCode 会直接插入labelsortText是候选排序权重前缀为0的项会排在没有sortText的项前面。参数说明CompletionItemKind有很多值——Keyword、Function、Variable、Module、Struct。它不只是装饰会影响 VSCode 对 item 的默认评分和图标选错分类有时会导致排序被压到很后面。需要插入复杂结构时把insertText设为vscode.SnippetString比如new vscode.SnippetString(repeat(${1:count}) {\n\t$0\n})这样插入后光标会自动落在占位符上。4.2 触发字符怎么传才生效以及如何按上下文切换补全项触发字符是registerCompletionItemProvider的第三个参数。很多人以为它写在某个配置里其实它就是你传入函数的那一串字符const provider vscode.languages.registerCompletionItemProvider( { language: mylang, scheme: file }, { provideCompletionItems(document, position) { const prefix document.lineAt(position.line).text.slice(0, position.character); if (prefix.endsWith()) { return [new vscode.CompletionItem(author, vscode.CompletionItemKind.Variable)]; } if (/import\s$/.test(prefix)) { return [new vscode.CompletionItem(widget, vscode.CompletionItemKind.Module)]; } return []; } }, , i );逻辑说明第三个参数支持多个触发字符和i都会被当成触发条件。用户输入到或i时VSCode 自动调用provideCompletionItems你不用关心用户是否按了 CtrlSpace。参数说明触发字符不是越多越好。把.加进去意味着用户每次敲点号都会触发一次补全请求如果 Provider 里有重逻辑手感会明显变差。context.triggerCharacter可以拿到具体触发字符便于精确区分场景。另外Provider 并不仅仅在触发字符出现时被调用。用户手动按 CtrlSpace 也会调用它所以返回[]是合法的表示“这里不该有候选”。4.3 给补全项去重和排序filterText 与 sortText 的边界补全项一多排序和匹配就变成玄学。两个字段你要先弄明白字段作用适用场景filterText过滤时使用的匹配文本label 不够直观用户可能输入别名sortText候选排序权重想让自定义项排在最前preselect是否预选为默认项候选很多时直接回车选中它range本次补全要替换的文本范围需要覆盖旧标识符而不是只插入常见误用是只改label不改sortText结果自定义项混在中间用户要翻几页才找到。直接给一个前缀策略const item new vscode.CompletionItem(repeat, vscode.CompletionItemKind.Keyword); item.sortText 0001; item.filterText rep complete loop; item.range new vscode.Range(position, position);逻辑说明sortText越大排序越靠后我习惯按优先级分成0001、0002、0003三段覆盖常用关键词、函数名、变量名。filterText可以写成多个关键词的组合这样用户输入complete、loop也能找到repeat。参数说明range是很关键但容易被忽略的字段。如果你在用户已有的标识符上补全不设置range的话候选文本会被追加到当前词后面产生variablenewVar这种脏结果。设置range为当前position到该词开头VSCode 会替换掉整段旧文本。5. 悬停提示与常见问题排查MarkdownString 渲染、异步取数、4 个踩坑记录悬停提示的实现看起来最简单但我实际花在它上面的定位时间最多。原因在于悬停是高频事件鼠标每划过一次就调用一次 Provider只要里面有异步请求或磁盘读卡顿和乱序问题马上浮现。5.1 HoverProvider 的最小实现与 MarkdownString 的正确打开方式HoverProvider 返回vscode.Hover内容是一个或多个MarkdownString。官方推荐用MarkdownString而不是普通字符串因为悬停会走 Markdown 渲染管线。provideHover(document, position) { const wordRange document.getWordRangeAtPosition(position); if (!wordRange) return null; const word document.getText(wordRange); const md new vscode.MarkdownString(); md.appendMarkdown(**${word}** 是 mylang 的保留关键字); md.appendMarkdown(\n\n示例); md.appendCodeblock(repeat(3) {\n print(ok)\n}, mylang); md.isTrusted false; return new vscode.Hover(md, wordRange); }逻辑说明appendMarkdown用来追加 Markdown 文本appendCodeblock专门插入代码块并自动做缩进处理。isTrustedfalse时悬停里的命令链接和 HTML 会被降级处理这是安全默认项不要轻易改成true。参数说明new vscode.Hover(md, wordRange)的第二个参数是让它只在这个区域内生效。如果你不传VSCode 会使用当前词的默认范围有时会拉伸整个生效区域导致鼠标移动到附近空白处也触发悬停。5.2 悬停内容别每次都现查缓存、Promise 与取消信号悬停的真实点击频率比 F12 高一个数量级。每次鼠标移动都查一遍文件用户会觉得卡片出来慢半拍。常用做法是激活时建立索引或缓存Provider 内只查 Map。const hoverCache new Mapstring, vscode.MarkdownString(); const pending new Mapstring, Promisevscode.MarkdownString | null(); function getDocForSymbol(word: string): Promisevscode.MarkdownString | null { if (hoverCache.has(word)) { return Promise.resolve(hoverCache.get(word)!); } if (pending.has(word)) { return pending.get(word)!; } const promise (async () { const loc await querySymbol(word); // 返回 Location 或 null if (!loc) return null; const doc await vscode.workspace.openTextDocument(loc.uri); const text doc.getText(loc.range); const md new vscode.MarkdownString(text.slice(0, 200)); // 只截取前 200 字符展示 hoverCache.set(word, md); return md; })(); pending.set(word, promise); promise.finally(() pending.delete(word)); return promise; }逻辑说明hoverCache存放已查过的结果pending防止同一个符号并发产生多次查询。这样鼠标在同一个符号上反复划过时只执行一次索引查询。参数说明querySymbol是你自己的索引查询函数它返回一个Location再用openTextDocument读取目标文件。注意openTextDocument是有代价的能缓存TextDocument就不要反复打开。截断到 200 字符是为了避免悬停卡片过长需要完整文档时再走展开逻辑。5.3 排查实录 4 条现象、原因与处理办法踩坑 1悬停内容里的代码块没有被渲染变成一大坨纯文本现象悬停卡片里代码只是换行显示没有语法高亮也没有代码块边框。原因直接用模板字符串拼了代码块标记缩进和空行被 Markdown 解析器吞掉了部分实现里还混了普通换行符。解决一律通过appendCodeblock(code, mylang)插入代码块不要自己拼反引号。我后来把悬停内容的生成全部收敛到一个工具函数里禁止手写拼接。踩坑 2F12 跳过去光标落到行首而不是定义符号上现象跳转成功但光标停在行首要再按一次 End 才能到定义词尾部。原因返回的Location里Range只用了new Position(i, 0)没有把起始列精确到符号首字母。解决用正则的match.index加doc.positionAt(offset)来计算或者统一用line.indexOf(word)。我在 3.2 和 3.3 里都留了这个细节。踩坑 3自动补全永远排在最后或者根本找不到现象输入几个字符想要的候选出现在列表末尾输入缩写时候选直接消失。原因没设置sortTextVSCode 按 label 默认排序没设置filterText输入别名无法命中。解决给自定义项加sortText: 0001这类前缀需要别名匹配时设置filterText。这个坑在 4.3 里有完整参数说明。踩坑 4触发字符设了但补全不弹出来现象注册时传了但用户输入没有候选。原因触发字符被写到了CompletionItem上而不是registerCompletionItemProvider的第三个参数里或者触发字符是中文符号但没匹配到。解决确认调用签名是registerCompletionItemProvider(selector, provider, ...triggerCharacters)。注意触发字符是可变参数多个字符直接依次追加。6. 最后一步用扩展开发宿主把三个功能一次验证到底附一个组合技巧到了这一步你应该已经有一个能注册、能返回基本结果的插件了。最后把调试和验证的路径固定下来这会比写代码本身省更多时间。6.1 扩展开发宿主里的三大验证动作最常见的验证姿势是按 F5 启动“扩展开发宿主”它会开一个新的 VSCode 窗口并加载你的插件。打开一个.mylang文件逐一验证# 第一个动作验证跳转 # 光标放到某个符号上按 F12看是否跳转到目标行 # 第二个动作验证补全 # 输入触发字符如“”看候选是否按预期出现、排序是否正确 # 第三个动作验证悬停 # 鼠标悬停在符号上观察 Markdown 是否渲染、代码块是否正常而验证不是一次性的。每次改代码按CtrlShiftP执行Developer: Reload Window重载插件宿主窗口比反复重启快得多。再推荐一个调试习惯不要只用console.log因为输出常常被插件宿主吞掉。更可靠的日志通道是 OutputChannelconst output vscode.window.createOutputChannel(mylang-ext); output.appendLine([provider] provideHover called for word);它会在“输出”面板里有一个独立标签还能持久化查看排查调用顺序和触发频率时非常直观。6.2 让三个 Provider 共享同一个符号索引三个 Provider 各自实现会造成同一份符号索引被重复构建三遍。我习惯写一个类同时实现三个接口class MylangApi implements vscode.DefinitionProvider, vscode.CompletionItemProvider, vscode.HoverProvider { private symbolTable new Mapstring, vscode.Location[](); async init() { await this.buildSymbolTable(); } provideDefinition(document, position) { const word this.extractWord(document, position); const locs this.symbolTable.get(word) || []; return locs.length 0 ? locs : null; } provideCompletionItems(document, position) { // 在这里只有一种场景要区分字符串内补全、普通代码补全 return this.buildCompletions(document, position); } provideHover(document, position) { const word this.extractWord(document, position); const entry this.symbolTable.get(word); return entry ? new vscode.Hover(this.markdownFor(entry)) : null; } } export async function activate(context: vscode.ExtensionContext) { const api new MylangApi(); await api.init(); context.subscriptions.push( vscode.languages.registerDefinitionProvider(selector, api), vscode.languages.registerCompletionItemProvider(selector, api, , i), vscode.languages.registerHoverProvider(selector, api) ); }逻辑说明一个类对象同时注册为三个 ProviderprovideDefinition、provideCompletionItems、provideHover都从同一个symbolTable里取数。激活时只建一次索引三个能力共享既省内存又不重复扫描。参数说明init()必须在注册之前完成否则用户打开文件时索引还是空的跳转会落空。如果索引很大可以把init()改成异步并行注册优先索引完成后在provideDefinition里查不到再触发一次buildSymbolTable()用 Promise 防并发即可。我早期实现的插件三份功能各写各的索引改一个符号规则要同步改三个地方翻车的概率很高。后来改成这种共享索引结构改动才收敛到一处。现在回头看跳转、补全、悬停这三个功能完全可以在一个类里协同工作代码量不增加反而减少排查路径也短了很多。希望这一篇能帮到你少走我走过的这些弯路。本文还有配套的精品资源点击获取 VSCode插件开发核心三件套：跳转定义、自动补全与悬停提示
简介面向VS Code插件开发者的实战资源系统讲解跳转到定义、自动补全、悬停提示三大核心能力的实现路径。内容以vscode.languages命名空间下的Provider机制为主线逐一解读registerDefinitionProvider、registerCompletionItemProvider、registerHoverProvider的注册方式、参数含义与返回值构造并结合package.json依赖包跳转、this.dependencies.xxx自动补全等贴近真实场景的示例代码演示Location、CompletionItem、Hover等对象的创建与使用同时点明高亮范围控制、activationEvents触发配置等易错细节。资源打包为1个PDF文件大小248KB结构紧凑适合快速通读或在插件开发时按需查阅PDF从注册Provider到返回定位、补全与悬停内容步骤环环相扣代码片段可直接迁移到自己的插件项目中。已有45553人学习下载尤其适合编写自定义语言服务、开发效率工具以及希望系统掌握VS Code插件机制的中高级前端开发者。1. 有人问我 VSCode 插件开发先学什么我永远先说跳转到定义、自动补全、悬停提示我第一次写 VSCode 插件开发时满脑子想的是侧边栏、状态栏、Webview 面板觉得这些才叫“做产品”。结果被同组做基础工具的同行问了一句“你这插件能把我的 F12 用起来吗”当场答不上来。后来想明白了VSCode 插件开发里真正决定实用性的不是界面而是跳转到定义、自动补全、悬停提示这三个能力。你把光标放到一个符号上能否按 F12 跳到定义输入到一半是否自动给出候选鼠标悬停是否有一句话说明来源——这三件事才是用户每天按几十次的路径。这一篇就是把这三个能力一次讲透的落地笔记。它不会停在 API 罗列而是把 Provider 的注册与返回类型、参数怎么设、哪些位置容易踩坑全按可复现的方式给你。新手照着最小命令能跑起来熟手可以直接跳到第 5 章的排查实录对照自己的实现。2. 先给机制定位激活事件、DocumentSelector 与三个 Provider 的注册关系这三个功能虽然入口不同但底层是同一套契约在package.json里声明语言在activate里注册 ProviderProvider 返回特定结构VSCode 负责把结果渲染成跳转、候选列表或悬停卡片。把这套契约搞清楚后面三分之二的坑都能提前避掉。2.1 用 onLanguage 而不是*来激活激活时机决定了首屏体验很多插件模板图省事直接在package.json里写activationEvents: [*]结果插件在 VSCode 启动时就全部加载。对于一个只处理.mylang文件的插件这是巨大的浪费用户打开编辑器会明显感觉卡顿。我一般会把激活事件收敛到语言维度{ activationEvents: [ onLanguage:mylang ], contributes: { languages: [ { id: mylang, extensions: [.mylang, .myl] } ] } }逻辑说明onLanguage:mylang表示只有用户打开这种语言的文件时插件才启动。只要contributes.languages里声明了idVSCode 会自动补一条隐式激活事件但显式写出来更直观后续要加onCommand、onStartupFinished时也能一眼看清。参数说明id必须与代码里DocumentSelector的language保持一致extensions数组里是关联的文件后缀。不建议用*也不建议把所有功能都挂在onStartupFinished上那会牺牲按需加载的优势。2.2 一个文件里注册三个 Provider最小可用骨架下面这段骨架代码可以放进extension.ts直接跑。它把跳转、补全、悬停三个注册都做了只是返回空值目的是先验证注册链路是通的。import * as vscode from vscode; export function activate(context: vscode.ExtensionContext) { const selector: vscode.DocumentSelector { language: mylang, scheme: file }; const defProvider vscode.languages.registerDefinitionProvider(selector, { provideDefinition(document, position) { return null; // 还没实现先不拦路 } }); const compProvider vscode.languages.registerCompletionItemProvider(selector, { provideCompletionItems(document, position) { return []; // 空数组表示没有候选 } }, .); // 第三个参数是触发字符按点号时自动弹出补全 const hoverProvider vscode.languages.registerHoverProvider(selector, { provideHover(document, position) { return null; // null 表示不处理交给其他插件 } }); context.subscriptions.push(defProvider, compProvider, hoverProvider); }逻辑说明三个 Provider 共用同一个selector它决定了这些能力只在.mylang文件里生效。context.subscriptions.push是标准收尾插件卸载时这些注册会被自动清理。参数说明scheme: file值得写清楚。如果插件面向本地文件加上scheme: file可以避免在“未保存的临时文档”或“预览文档”里误触发如果还要支持 Git 差异视图就得改成scheme: file, untitled, git或直接用语言匹配。2.3 返回类型决定交互Location、CompletionList 和 Hover 的契约三个 Provider 的返回值直接影响 VSCode 的交互形式我整理成一张对照表Provider接口方法空返回值行为异常行为DefinitionProviderprovideDefinition继续匹配其他插件该提供者被禁用CompletionItemProviderprovideCompletionItems无候选退回内置词该提供者被禁用HoverProviderprovideHover无悬停内容该提供者被禁用参数说明三个方法都可以返回null表示“我不处理”。但如果你抛出异常VSCode 会把当前 Provider 标记为异常状态后续调用全部失效。所以我在实现里会用 try/catch 包一层记录日志后返回null而不是让异常冒泡。这里的核心思维是Provider 只是“提供内容”渲染和交互是 VSCode 的职责。你返回LocationVSCode 画跳转箭头和预览框你返回CompletionItem[]它做候选排序和筛选你返回Hover它渲染悬停卡片。理解了这层边界就不会把 UI 逻辑写进插件里。3. 跳到定义从最小返回 Location 到跨文件符号定位跳转到定义是三个能力里最重的因为用户对 VSCode 的预期已经被 C/C 和 TypeScript 拉到很高F12 要准、要快、要能跨文件。我们自己实现的语言插件水准线可以不用追平大型语言服务器但至少要做到“按 F12 不落空”。3.1 三种返回值的差异Location、LocationLink 与多定义位置跳转 Provider 的返回值最常见的写法是new vscode.Location(uri, range)。uri是目标文件的资源标识range是定义位置的行列范围。一个Location就够用但有几个边界你要提前知道。第一返回数组时VSCode 会打开 Peek 面板让你选择。常用于“多个文件里都有同名定义”的场景。注意数组非空时 VSCode 不会直接跳转而是先展示选择列表如果你的插件永远只返回一个结果返回单个Location体验最顺。第二LocationLink提供更精细的控制包含originSelectionRange、targetUri、targetRange、targetSelectionRange。用它的好处是预览框里高亮的范围可以精确到标识符而不是整行。多文件选择场景下我通常优先返回LocationLink[]。第三range本身要精确定位到定义符号上。最常见的坑是只给行号不给列导致跳过去后光标落在行首而不是落在def foo的foo上。这个后面排查实录里细说。3.2 最小可用的 DefinitionProvider在当前文件里定位定义先从单文件场景入手。假设我们的.mylang文件里定义语句长这样def foo: return 1那最小实现就是遍历所有行找def 标识符行返回一个LocationprovideDefinition(document, position) { const wordRange document.getWordRangeAtPosition(position); if (!wordRange) return null; const word document.getText(wordRange); const pattern /^def\s([A-Za-z_]\w*)/; for (let i 0; i document.lineCount; i) { const line document.lineAt(i).text; const match line.match(pattern); if (match match[1] word) { const startPos new vscode.Position(i, match.index 4); const endPos startPos.translate(0, word.length); return new vscode.Location(document.uri, new vscode.Range(startPos, endPos)); } } return null; }逻辑说明getWordRangeAtPosition先拿到光标下的单词及其范围document.getText(wordRange)提取出单词本身。正则^def\s匹配定义行match.index 4是跳过def前缀后的起始列。参数说明这里的 4 是指def加一个空格的长度如果定义语法改成define或fn这个偏移量必须同步改否则跳转位置会错。更稳的做法是用line.indexOf(match[1])来定位避免硬编码前缀长度。如果你的标识符包含中文或连字符getWordRangeAtPosition默认的单词规则会失效可以传入第二个参数自定义正则const wordRange document.getWordRangeAtPosition( position, /[\w\u4e00-\u9fa5-]/ );3.3 跨文件跳转findFiles 建索引并缓存到内存单文件跳转太局限真实场景里定义往往分散在多个文件。一个可靠做法是插件激活时扫描一次工作区把符号建立索引之后每次跳转都只查内存中的 Map。class DefIndex { private cache new Mapstring, vscode.Location[](); async build(): Promisevoid { const uris await vscode.workspace.findFiles(**/*.defs); for (const uri of uris) { const doc await vscode.workspace.openTextDocument(uri); const text doc.getText(); const pattern /^def\s([A-Za-z_]\w*)/gm; let match: RegExpExecArray | null; while ((match pattern.exec(text))) { const name match[1]; const startPos doc.positionAt(match.index 4); const endPos startPos.translate(0, name.length); const loc new vscode.Location(uri, new vscode.Range(startPos, endPos)); const list this.cache.get(name) || []; list.push(loc); this.cache.set(name, list); } } } get(name: string): vscode.Location[] { return this.cache.get(name) || []; } }逻辑说明findFiles(**/*.defs)只匹配扩展名为.defs的文件避免把源码目录里的无用文件也扫进来。openTextDocument只是读取内容不会弹出编辑器窗口。positionAt会把字符偏移量换算成行列位置这是和前面手工计算列号完全不同的思路更不容易出错。参数说明findFiles的 glob 默认不会遍历node_modules和隐藏目录这对插件来说通常是好事。如果你确实要包含需要传findFiles(include, exclude, maxResults)第二个参数写**/{node_modules,.git}/**来覆盖默认排除。缓存建立之后别忘了在文件保存时做失效处理避免用户改了定义文件但跳转还指向旧行vscode.workspace.onDidSaveTextDocument((doc) { if (doc.languageId mylang || doc.uri.path.endsWith(.defs)) { index.build(); // 或者只重建这一个文件对应的符号量小就全量重建 } });4. 自动补全CompletionItem 字段、触发字符与排序的完整取舍自动补全是用户感知最强的能力因为你每敲一个字符候选列表就贴在你光标下方。做得粗糙和做得细腻的区别全在字段设置上。4.1 CompletionItem 里要调的字段label、kind、insertText、sortText先看一个能直接运行的补全提供者provideCompletionItems(document, position) { const keywords [if, repeat, done, else]; return keywords.map(name { const item new vscode.CompletionItem(name, vscode.CompletionItemKind.Keyword); item.detail mylang 关键字; item.documentation new vscode.MarkdownString(**${name}** 是保留关键字); item.insertText name ; item.sortText 0 name; return item; }); }逻辑说明label是候选列表里展示的文字也是默认的插入文本kind决定左侧图标和右侧的分类标签insertText如果不设置VSCode 会直接插入labelsortText是候选排序权重前缀为0的项会排在没有sortText的项前面。参数说明CompletionItemKind有很多值——Keyword、Function、Variable、Module、Struct。它不只是装饰会影响 VSCode 对 item 的默认评分和图标选错分类有时会导致排序被压到很后面。需要插入复杂结构时把insertText设为vscode.SnippetString比如new vscode.SnippetString(repeat(${1:count}) {\n\t$0\n})这样插入后光标会自动落在占位符上。4.2 触发字符怎么传才生效以及如何按上下文切换补全项触发字符是registerCompletionItemProvider的第三个参数。很多人以为它写在某个配置里其实它就是你传入函数的那一串字符const provider vscode.languages.registerCompletionItemProvider( { language: mylang, scheme: file }, { provideCompletionItems(document, position) { const prefix document.lineAt(position.line).text.slice(0, position.character); if (prefix.endsWith()) { return [new vscode.CompletionItem(author, vscode.CompletionItemKind.Variable)]; } if (/import\s$/.test(prefix)) { return [new vscode.CompletionItem(widget, vscode.CompletionItemKind.Module)]; } return []; } }, , i );逻辑说明第三个参数支持多个触发字符和i都会被当成触发条件。用户输入到或i时VSCode 自动调用provideCompletionItems你不用关心用户是否按了 CtrlSpace。参数说明触发字符不是越多越好。把.加进去意味着用户每次敲点号都会触发一次补全请求如果 Provider 里有重逻辑手感会明显变差。context.triggerCharacter可以拿到具体触发字符便于精确区分场景。另外Provider 并不仅仅在触发字符出现时被调用。用户手动按 CtrlSpace 也会调用它所以返回[]是合法的表示“这里不该有候选”。4.3 给补全项去重和排序filterText 与 sortText 的边界补全项一多排序和匹配就变成玄学。两个字段你要先弄明白字段作用适用场景filterText过滤时使用的匹配文本label 不够直观用户可能输入别名sortText候选排序权重想让自定义项排在最前preselect是否预选为默认项候选很多时直接回车选中它range本次补全要替换的文本范围需要覆盖旧标识符而不是只插入常见误用是只改label不改sortText结果自定义项混在中间用户要翻几页才找到。直接给一个前缀策略const item new vscode.CompletionItem(repeat, vscode.CompletionItemKind.Keyword); item.sortText 0001; item.filterText rep complete loop; item.range new vscode.Range(position, position);逻辑说明sortText越大排序越靠后我习惯按优先级分成0001、0002、0003三段覆盖常用关键词、函数名、变量名。filterText可以写成多个关键词的组合这样用户输入complete、loop也能找到repeat。参数说明range是很关键但容易被忽略的字段。如果你在用户已有的标识符上补全不设置range的话候选文本会被追加到当前词后面产生variablenewVar这种脏结果。设置range为当前position到该词开头VSCode 会替换掉整段旧文本。5. 悬停提示与常见问题排查MarkdownString 渲染、异步取数、4 个踩坑记录悬停提示的实现看起来最简单但我实际花在它上面的定位时间最多。原因在于悬停是高频事件鼠标每划过一次就调用一次 Provider只要里面有异步请求或磁盘读卡顿和乱序问题马上浮现。5.1 HoverProvider 的最小实现与 MarkdownString 的正确打开方式HoverProvider 返回vscode.Hover内容是一个或多个MarkdownString。官方推荐用MarkdownString而不是普通字符串因为悬停会走 Markdown 渲染管线。provideHover(document, position) { const wordRange document.getWordRangeAtPosition(position); if (!wordRange) return null; const word document.getText(wordRange); const md new vscode.MarkdownString(); md.appendMarkdown(**${word}** 是 mylang 的保留关键字); md.appendMarkdown(\n\n示例); md.appendCodeblock(repeat(3) {\n print(ok)\n}, mylang); md.isTrusted false; return new vscode.Hover(md, wordRange); }逻辑说明appendMarkdown用来追加 Markdown 文本appendCodeblock专门插入代码块并自动做缩进处理。isTrustedfalse时悬停里的命令链接和 HTML 会被降级处理这是安全默认项不要轻易改成true。参数说明new vscode.Hover(md, wordRange)的第二个参数是让它只在这个区域内生效。如果你不传VSCode 会使用当前词的默认范围有时会拉伸整个生效区域导致鼠标移动到附近空白处也触发悬停。5.2 悬停内容别每次都现查缓存、Promise 与取消信号悬停的真实点击频率比 F12 高一个数量级。每次鼠标移动都查一遍文件用户会觉得卡片出来慢半拍。常用做法是激活时建立索引或缓存Provider 内只查 Map。const hoverCache new Mapstring, vscode.MarkdownString(); const pending new Mapstring, Promisevscode.MarkdownString | null(); function getDocForSymbol(word: string): Promisevscode.MarkdownString | null { if (hoverCache.has(word)) { return Promise.resolve(hoverCache.get(word)!); } if (pending.has(word)) { return pending.get(word)!; } const promise (async () { const loc await querySymbol(word); // 返回 Location 或 null if (!loc) return null; const doc await vscode.workspace.openTextDocument(loc.uri); const text doc.getText(loc.range); const md new vscode.MarkdownString(text.slice(0, 200)); // 只截取前 200 字符展示 hoverCache.set(word, md); return md; })(); pending.set(word, promise); promise.finally(() pending.delete(word)); return promise; }逻辑说明hoverCache存放已查过的结果pending防止同一个符号并发产生多次查询。这样鼠标在同一个符号上反复划过时只执行一次索引查询。参数说明querySymbol是你自己的索引查询函数它返回一个Location再用openTextDocument读取目标文件。注意openTextDocument是有代价的能缓存TextDocument就不要反复打开。截断到 200 字符是为了避免悬停卡片过长需要完整文档时再走展开逻辑。5.3 排查实录 4 条现象、原因与处理办法踩坑 1悬停内容里的代码块没有被渲染变成一大坨纯文本现象悬停卡片里代码只是换行显示没有语法高亮也没有代码块边框。原因直接用模板字符串拼了代码块标记缩进和空行被 Markdown 解析器吞掉了部分实现里还混了普通换行符。解决一律通过appendCodeblock(code, mylang)插入代码块不要自己拼反引号。我后来把悬停内容的生成全部收敛到一个工具函数里禁止手写拼接。踩坑 2F12 跳过去光标落到行首而不是定义符号上现象跳转成功但光标停在行首要再按一次 End 才能到定义词尾部。原因返回的Location里Range只用了new Position(i, 0)没有把起始列精确到符号首字母。解决用正则的match.index加doc.positionAt(offset)来计算或者统一用line.indexOf(word)。我在 3.2 和 3.3 里都留了这个细节。踩坑 3自动补全永远排在最后或者根本找不到现象输入几个字符想要的候选出现在列表末尾输入缩写时候选直接消失。原因没设置sortTextVSCode 按 label 默认排序没设置filterText输入别名无法命中。解决给自定义项加sortText: 0001这类前缀需要别名匹配时设置filterText。这个坑在 4.3 里有完整参数说明。踩坑 4触发字符设了但补全不弹出来现象注册时传了但用户输入没有候选。原因触发字符被写到了CompletionItem上而不是registerCompletionItemProvider的第三个参数里或者触发字符是中文符号但没匹配到。解决确认调用签名是registerCompletionItemProvider(selector, provider, ...triggerCharacters)。注意触发字符是可变参数多个字符直接依次追加。6. 最后一步用扩展开发宿主把三个功能一次验证到底附一个组合技巧到了这一步你应该已经有一个能注册、能返回基本结果的插件了。最后把调试和验证的路径固定下来这会比写代码本身省更多时间。6.1 扩展开发宿主里的三大验证动作最常见的验证姿势是按 F5 启动“扩展开发宿主”它会开一个新的 VSCode 窗口并加载你的插件。打开一个.mylang文件逐一验证# 第一个动作验证跳转 # 光标放到某个符号上按 F12看是否跳转到目标行 # 第二个动作验证补全 # 输入触发字符如“”看候选是否按预期出现、排序是否正确 # 第三个动作验证悬停 # 鼠标悬停在符号上观察 Markdown 是否渲染、代码块是否正常而验证不是一次性的。每次改代码按CtrlShiftP执行Developer: Reload Window重载插件宿主窗口比反复重启快得多。再推荐一个调试习惯不要只用console.log因为输出常常被插件宿主吞掉。更可靠的日志通道是 OutputChannelconst output vscode.window.createOutputChannel(mylang-ext); output.appendLine([provider] provideHover called for word);它会在“输出”面板里有一个独立标签还能持久化查看排查调用顺序和触发频率时非常直观。6.2 让三个 Provider 共享同一个符号索引三个 Provider 各自实现会造成同一份符号索引被重复构建三遍。我习惯写一个类同时实现三个接口class MylangApi implements vscode.DefinitionProvider, vscode.CompletionItemProvider, vscode.HoverProvider { private symbolTable new Mapstring, vscode.Location[](); async init() { await this.buildSymbolTable(); } provideDefinition(document, position) { const word this.extractWord(document, position); const locs this.symbolTable.get(word) || []; return locs.length 0 ? locs : null; } provideCompletionItems(document, position) { // 在这里只有一种场景要区分字符串内补全、普通代码补全 return this.buildCompletions(document, position); } provideHover(document, position) { const word this.extractWord(document, position); const entry this.symbolTable.get(word); return entry ? new vscode.Hover(this.markdownFor(entry)) : null; } } export async function activate(context: vscode.ExtensionContext) { const api new MylangApi(); await api.init(); context.subscriptions.push( vscode.languages.registerDefinitionProvider(selector, api), vscode.languages.registerCompletionItemProvider(selector, api, , i), vscode.languages.registerHoverProvider(selector, api) ); }逻辑说明一个类对象同时注册为三个 ProviderprovideDefinition、provideCompletionItems、provideHover都从同一个symbolTable里取数。激活时只建一次索引三个能力共享既省内存又不重复扫描。参数说明init()必须在注册之前完成否则用户打开文件时索引还是空的跳转会落空。如果索引很大可以把init()改成异步并行注册优先索引完成后在provideDefinition里查不到再触发一次buildSymbolTable()用 Promise 防并发即可。我早期实现的插件三份功能各写各的索引改一个符号规则要同步改三个地方翻车的概率很高。后来改成这种共享索引结构改动才收敛到一处。现在回头看跳转、补全、悬停这三个功能完全可以在一个类里协同工作代码量不增加反而减少排查路径也短了很多。希望这一篇能帮到你少走我走过的这些弯路。本文还有配套的精品资源点击获取