如何使用Code Tour插件为你的VSCode项目创建交互式导览

Code Tour 是 VS Code 官方轻量交互式代码导览插件，以 JSON 文件存于项目中，支持 Markdown 注释、步骤跳转、命令执行、条件显示及变量注入，开箱即用，适合上手引导与教学。

Code Tour 插件能帮你为 VS Code 项目创建轻量、可运行、带注释的交互式导览，适合新成员上手、代码评审说明或教学演示。它不依赖外部服务，所有内容以 JSON 文件形式存于项目中，开箱即用。

安装与基础配置

在 VS Code 扩展市场搜索 “Code Tour”，安装由 Microsoft 发布的官方插件（图标为指南针）。安装后无需额外配置，重启 VS Code 即可生效。项目根目录下会自动生成 .code-tour 文件夹（首次创建导览时自动建立），里面存放每个导览的 JSON 文件，例如 onboarding.tour 或 auth-flow.tour。

快速创建第一个导览

打开你想引导的源码文件（如 src/App.tsx），右键选择 “Create Code Tour”，输入名称（如 “App 组件概览”），回车确认。接着在关键行号上右键 → “Add Step”，输入说明文字（支持 Markdown，如加粗、列表、代码块）。每步可指定文件、行号、焦点区域（如 12-15）和可选命令（如 “保存文件”、“运行测试”）。

• 步骤支持跳转：点击步骤中的文件路径或行号，自动打开并定位
• 可插入命令：比如 workbench.action.terminal.toggleTerminal 打开终端
• 支持条件跳过：用 "when": "editorTextFocus && editorLangId == 'typescript' 控制显示逻辑

运行与分享导览

按 Ctrl+Shift+P（Win/Linux）或 Cmd+Shift+P（Mac），输入 “Code Tour: Start Tour”，选择对应 .tour 文件即可启动。界面左侧出现导航面板，支持播放/暂停、跳步、返回、退出。导览过程中编辑器聚焦变化、高亮当前行，体验接近真实讲解。

• 导览文件是纯 JSON，可直接提交到 Git，团队成员拉取后立即可用
• 支持多语言：步骤描述中嵌入中文无问题，语法高亮随当前文件语言自动匹配
• 可在 README.md 中添加链接：[查看登录流程导览](.code-tour/auth-flow.tour)，VS Code 点击即启动

进阶技巧与注意事项

导览不是静态文档，而是“可执行的上下文”。你可以用变量注入动态信息，比如 ${workspaceFolder} 或 ${fileBasename}；也可用 "autoReveal": false 避免自动滚动干扰用户操作。注意避免步骤过多（建议单个导览 ≤ 12 步），复杂流程可拆分为多个主题导览（如 “数据获取”、“错误处理”、“状态更新”）。

• 修改导览后无需重启 VS Code，保存 JSON 即实时生效
• 删除某步？直接在 .tour 文件中删掉对应 step 对象，或右键步骤 → “Remove Step”
• 调试提示：若步骤不显示，检查文件路径是否为相对路径（推荐用 ./src/...）、行号是否存在

基本上就这些。Code Tour 的价值不在炫技，而在把“口头说一遍”的引导，变成可复现、可迭代、可沉淀的轻量交互资产。