VSCode使用CodeTour功能_为新团队成员制作代码功能讲解导览

CodeTour插件已不可用，微软于2023年底正式弃用并下架该扩展，当前搜索到的多为不兼容原格式的社区复刻版。

CodeTour插件是否还可用？2024年真实状态

先说一个明确的结论：CodeTour插件的官方生命已经终结。早在2023年底，微软就正式弃用了它，那个熟悉的vscode-code-tour扩展已经从市场下架，自然也不再有任何更新。如果你现在去VSCode扩展商店里搜索“CodeTour”，跳出来的结果多半是社区爱好者维护的复刻版本，比如code-tour-community这类。但需要警惕的是，这些复刻版往往“水土不服”——它们无法兼容原版的导览数据格式，更关键的是，对于GitHub Codespaces或者VSCode新版引入的WebWorker沙箱机制，基本都束手无策。

替代方案：用内置的 vscode-notebook + 自定义 Markdown 导览

那么，没有官方插件，团队新人上手代码库的导览需求就无解了吗？当然不是。其实，思路可以更直接一些：我们的核心目标，是让新人点击一段文字说明，编辑器就能自动定位到对应的代码行并高亮显示。至于用什么技术实现，反而可以更灵活。

VSCode本身其实就藏着一个好用的工具——原生的Notebook支持（需要手动在设置里启用notebook.experimental.enableDefaultNotebook）。配合一点轻量级的脚本，完全能打造出媲美CodeTour的交互体验。具体怎么做？

• 第一步，在项目里新建一个onboarding.code-notebook文件，类型就选“Plain Text Notebook”。
• 接下来，把每一步的讲解写在Markdown单元格里。关键技巧来了：在每个单元格的末尾，加上一行特殊的注释，比如，用来指明要跳转的目标位置。
• 然后，在项目根目录写一个极简的goto.js脚本。这个脚本的任务就是解析上面那种注释，并调用VSCode的APIvscode.window.showTextDocument()来完成跳转。
• 最后，给这个脚本绑定一个快捷键（比如Ctrl+Alt+G）。这样一来，整个流程就通了：看说明，按快捷键，立刻跳转到代码。全程无需安装任何第三方扩展。

为什么不用第三方 Tour 插件？常见踩坑点

你可能会问，既然有社区复刻版，为什么还要自己折腾？这里面的坑，可不少。很多复刻插件为了实现文件定位，严重依赖vscode.workspace.findFiles()或者vscode.workspace.textDocuments这类API来实时扫描项目。在小型项目里或许还行，但一旦遇到大型的Monorepo项目，卡顿就成了家常便饭。

更让人头疼的是路径解析问题。现在很多TypeScript项目都会使用路径别名来简化导入，比如@/hooks。但多数复刻插件根本无法正确识别这种别名。当导览配置里写着goto: "@/hooks/useApi"时，插件只会直接报错File not found，然后——通常就静默跳过了。新人点了没反应，完全不知道发生了什么，只会觉得这个导览工具是坏的。

• 除了路径问题，视觉体验上也有瑕疵。所有依赖装饰器（decoration）实现代码高亮的逻辑，在用户开启了"editor.smoothScrolling": true（平滑滚动）这个设置时，高亮区域经常会偏移那么一两行，对不准。
• 最后是协作层面的麻烦。导览步骤通常被保存为一个JSON配置文件。当两个团队成员同时修改了导览的第5步，合并代码时，面对那一大段结构化的JSON差异，解决冲突简直是一场噩梦，可读性极差。

真正轻量可靠的方案：纯 Markdown + 链接锚点

如果你觉得上面自定义Notebook的方案还是有点复杂，那么，还有一个更简单、更稳定、零依赖的“终极方案”：放弃“自动跳转”的幻想，直接拥抱VSCode原生就支持的功能——file:///链接加行号锚点。

是的，VSCode可以直接识别并打开这种格式的链接，点击后会自动打开对应文件并滚动到指定行。这个功能在Windows、macOS和Linux上全平台支持。

• 具体操作很简单：在项目的./docs/guide.md文档里，你需要这样写：[查看登录逻辑](file:///path/to/your/project/src/pages/Login.vue#L87)。
• 这里有个细节：路径必须是绝对路径。为了适配不同成员的本地环境，可以使用${workspaceFolder}这样的变量（需要在VSCode设置中启用markdown.preview.useWorkspaceRoot）。
• 为了让长篇导览文档更易读，可以配合markdown.extension.footnotes这类插件，把每一步的详细讲解写成带编号的脚注，避免主文档过长导致阅读时迷失方向。
• 在团队全面推行前，建议先执行一次code --goto ./src/main.ts:1这样的命令，验证一下本地的file://链接协议是否生效。有些企业的IT策略可能会禁用这类本地文件协议。

当然，这个方案最考验人的地方在于路径的拼写和系统权限。file://链接对路径中的空格、中文字符以及其他特殊符号都极其敏感，稍有不慎，点击链接就会打开一个空白页。因此，一个务实的建议是：所有用在链接里的路径，都统一用Node.js的path.posix.join()方法格式化一遍。更进一步，可以在持续集成（CI）流程里加入一个检查脚本，自动验证文档中所有的file://链接是否指向真实存在的文件，把问题扼杀在合并之前。