示例工程【免费下载链接】vscode-extension-samplesSample code illustrating the VS Code extension API.项目地址https://gitcode.com/gh_mirrors/vs/vscode-extension-samples点击查看免费下载本指南以 vscode-extension-samples 仓库中的 uri-handler-sample 为例讲解如何在 VS Code 扩展中实现 Uri Handler当浏览器或其他外部程序将带有扩展 id 作为 authority 的vscode://链接重定向到 VS Code 时扩展如何接收并处理该 Uri。读完本文你将掌握window.registerUriHandler、env.uriScheme、env.asExternalUri与UriHandler四个核心 API 的完整用法并能独立实现一个可被外部链接唤醒的 VS Code 扩展。Uri Handler 是什么Uri Handler 是 VS Code 提供的一种扩展机制当浏览器或系统级链接把形如vscode://vscode-samples.uri-handler-sample的链接交给 VS Code 打开时VS Code 会解析该链接并将链接中的 Uri 派发给注册了对应 authority即扩展 id的扩展进行处理。以本仓库示例为例下面两个链接分别会唤起 VS Code 稳定版与 Insiders 版vscode://vscode-samples.uri-handler-samplevscode-insiders://vscode-samples.uri-handler-sample其中链接的scheme协议头是vscode或vscode-insiders对应要唤起的 VS Code 版本链接的authority主机部分是扩展 id示例中为vscode-samples.uri-handler-sampleVS Code 据此找到目标扩展。把这两个链接粘贴到浏览器地址栏回车就会分别打开 VS Code 与 VS Code Insiders并把链接交给对应扩展处理。注意如果示例跑在 Insiders 中请使用vscode-insiders://前缀的链接。示例行为一览该示例实现了一个最简单的 Uri Handler每当一个 Uri 被处理后扩展会弹出一条信息提示如果 Uri 中带有查询字符串query提示信息中会一并展示。运行示例后在浏览器中依次打开以下链接即可看到效果vscode://vscode-samples.uri-handler-sample—— 弹出 Handled a Uri! 提示vscode://vscode-samples.uri-handler-sample?qhello—— 弹出 Handled a Uri! It came with this query: qhello 提示完整源码逐行解读示例的全部逻辑位于 src/extension.ts分为两部分自定义的MyUriHandler类和activate入口函数。1. 实现 UriHandler 接口import * as vscode from vscode; // Our implementation of a UriHandler. class MyUriHandler implements vscode.UriHandler { // This function will get run when something redirects to VS Code // with your extension id as the authority. handleUri(uri: vscode.Uri): vscode.ProviderResultvoid { let message Handled a Uri!; if (uri.query) { message It came with this query: ${uri.query}; } vscode.window.showInformationMessage(message); } }关键点自定义类必须实现vscode.UriHandler接口核心方法是handleUri(uri: vscode.Uri)。handleUri会在外部程序以扩展 id 作为 authority 重定向到 VS Code 时被调用参数uri就是浏览器传入的完整链接对象。示例中通过uri.query读取查询字符串并将处理结果用vscode.window.showInformationMessage以信息提示条展示。返回值类型为vscode.ProviderResultvoid意味着handleUri可以返回void、undefined、null或Promisevoid你可以在其中执行异步任务。2. 注册命令并启动 Uri 处理export function activate(context: vscode.ExtensionContext) { const disposable vscode.commands.registerCommand(uri-handler-sample.start, async () { // Create our new UriHandler const uriHandler new MyUriHandler(); // And register it with VS Code. You can only register a single UriHandler for your extension. context.subscriptions.push(vscode.window.registerUriHandler(uriHandler)); // You dont have to get the Uri from the vscode.env.asExternalUri API but it will add a query // parameter (ex: windowId%3D14) that will help VS Code decide which window to redirect to. // If this query parameter isnt specified, VS Code will pick the last windows that was focused. const uri await vscode.env.asExternalUri(vscode.Uri.parse(${vscode.env.uriScheme}://vscode-samples.uri-handler-sample)); vscode.window.showInformationMessage(Starting to handle Uris. Open ${uri} in your browser to test.); }); context.subscriptions.push(disposable); }流程拆解通过vscode.commands.registerCommand注册命令uri-handler-sample.start对应命令面板中的Start handling Uris。命令执行时先new MyUriHandler()创建处理器实例。调用vscode.window.registerUriHandler(uriHandler)将处理器注册到 VS Code注册后的 Disposable 推入context.subscriptions随扩展停用自动释放。调用vscode.env.asExternalUri生成一个可以在浏览器中打开的外部链接并在提示信息中展示方便用户直接点击测试。四个核心 API 详解window.registerUriHandlerregisterUriHandler(handler: UriHandler): Disposable用于将一个UriHandler注册到当前 VS Code 窗口。注册后任何以本扩展 id 为 authority 的vscode://链接都会路由到该处理器。重要限制源码注释中明确说明一个扩展只能注册一个 UriHandler。如果重复注册后注册的会覆盖先注册的因此设计 API 面时要确保整个扩展只维护一个处理实例。UriHandler 接口interface UriHandler { handleUri(uri: Uri): ProviderResultvoid; }接口只有一个方法handleUri。VS Code 文档约定handleUri返回的 Promise只有在 Uri 处理完成后才应 resolve——因为 VS Code 会在handleUri执行期间缓存后续到达的 Uri直到当前 Uri 处理完毕即 Promise resolve后才派发下一个。如果你的处理逻辑是异步的务必把整个处理过程包在返回的 Promise 中而不是立即返回。env.uriSchemevscode.env.uriScheme返回当前 VS Code 实例使用的 Uri scheme 字符串稳定版vscodeInsiders 版vscode-insiders其他构建/探索版对应各自的 scheme示例源码中用它动态拼接 Uri${vscode.env.uriScheme}://vscode-samples.uri-handler-sample这样同一份代码在稳定版和 Insiders 中都能生成正确前缀的链接无需硬编码。env.asExternalUriasExternalUri(target: Uri): PromiseUri把扩展内部使用的 Uri 转换为一个可在 VS Code 外部如浏览器打开的外部 Uri。在示例中它把vscode://vscode-samples.uri-handler-sample这样的内部 Uri 转成用户可以直接点击打开的外部链接。windowId 查询参数机制示例源码注释指出通过asExternalUri生成链接时会自动附带一个查询参数如windowId%3D14即 URL 编码后的windowId14。VS Code 会借助这个参数决定把链接重定向到哪个窗口——通常是你当前正在使用的那个窗口。如果没有该参数VS Code 会退而选择最近获得过焦点的窗口。因此示例特别推荐通过asExternalUri来生成测试链接而不是手写 Uri 字符串。扩展清单命令贡献点命令uri-handler-sample.start在 package.json 中通过contributes.commands声明contributes: { commands: [ { command: uri-handler-sample.start, title: Start handling Uris } ] }配套的工程配置要点publisher: vscode-samples与链接 authority 中的扩展 idvscode-samples.uri-handler-sample对应实际开发中authority 就是发布者.扩展名。engines: { vscode: ^1.100.0 }声明扩展所需的最低 VS Code 版本types/vscode也锁定在^1.100.0确保 Uri Handler 相关 API 类型可用。main: ./out/extension.js编译产物入口配合 tsconfig.json 中的rootDir: src、outDir: out、strict: true进行 TypeScript 编译。运行与调试步骤用 VS Code Insiders 打开uri-handler-sample目录uri-handler-sample。在终端执行npm install安装依赖。执行npm run watch启动 TypeScript 增量编译对应脚本tsc -watch -p ./。按F5启动扩展开发宿主Extension Development Host。在命令面板Ctrl/CmdShiftP运行Start handling Uris命令。在系统浏览器中打开提示信息里展示的链接或手输vscode://vscode-samples.uri-handler-sample?qhello即可看到扩展弹出的处理提示。若在 Insiders 中运行记得把链接前缀换成vscode-insiders://。典型应用场景与注意事项Uri Handler 在实际扩展中的典型用途包括OAuth / 第三方登录回调授权服务把vscode://回调链接交回扩展完成令牌交换可参考仓库中 github-authentication-sample 的凭据处理思路。深链接唤醒从网页、文档或系统协议跳转到扩展的指定功能页。跨窗口/跨实例协同借助asExternalUri与windowId参数把外部操作引导到正确的 VS Code 窗口。需要留意的事项每个扩展只能注册一个UriHandler。没有windowId参数时VS Code 会把链接路由到最近聚焦的窗口行为可能与预期不符建议始终通过asExternalUri生成对外链接。handleUri的异步处理必须完整地包裹在返回的 Promise 中避免提前 resolve 导致后续 Uri 排队积压。authority 必须是发布者.扩展名格式的扩展 id否则 VS Code 无法定位目标扩展。赞分享示例工程【免费下载链接】vscode-extension-samplesSample code illustrating the VS Code extension API.项目地址https://gitcode.com/gh_mirrors/vs/vscode-extension-samples点击查看免费下载相关推荐Aspire VS Code 扩展实战运行与调试 AppHost 完整指南Aspire VS Code 扩展实战运行与调试 AppHost 完整指南 本指南围绕 Aspire VS Code 扩展的“运行你的应用”Run your云原生后端微服务可观测性开发工具OpenCode VS Code扩展AI编程助手的完整实战指南OpenCode VS Code扩展AI编程助手的完整实战指南 OpenCode VS Code扩展作为新一代AI编程助手工具通过深度集成智能终端能力为开人工智能AI 应用AI Agent代码智能体CLI开发者工具5分钟快速上手bongocat-osuWindows和Linux完整安装教程5分钟快速上手bongocat osuWindows和Linux完整安装教程 bongocat osu是一款专为osu!玩家设计的Bongo Cat覆盖层工具上一篇Lerna 版本演进与升级指南从 v3 到 v10 的关键变更、破坏性改动与迁移实践下一篇从新手到专家UKUI桌面环境图标管理与右键菜单高效操作指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考