VSCode 的 CodeTour 插件可创建交互式代码导览，操作包括：一、安装启用插件；二、初始化 .code-tour 文件；三、右键添加单步注释；四、跨文件手动添加多步骤；五、启动播放并跳转导航。
如果您希望为团队成员或新贡献者提供对代码库结构和关键逻辑的直观理解，VSCode 的 CodeTour 插件可帮助您构建可运行、可跳转、带注释的交互式导览。以下是创建此类导览的具体操作步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、安装并启用 CodeTour 插件
CodeTour 是一个开源 VSCode 扩展，它允许用户在源码中嵌入结构化导览步骤，并以侧边栏形式呈现导航流程。启用该插件是创建导览的前提条件。
1、打开 VSCode，点击左侧活动栏中的扩展图标（或按 Cmd+Shift+X）。
2、在搜索框中输入 CodeTour，找到由 Microsoft 发布的官方插件。
3、点击“安装”按钮，安装完成后点击“重新加载”使插件生效。
二、初始化新 Tour 文件
每个导览以独立的 .code-tour 文件形式存在，该文件定义了步骤顺序、目标文件路径及注释内容。初始化操作将生成符合 JSON Schema 的空导览模板。
1、在 VSCode 中打开目标代码库的根目录。
2、按下 Cmd+Shift+P 打开命令面板，输入并选择 CodeTour: Create New Tour。
3、在弹出的输入框中为导览命名，例如 GettingStarted，回车确认。
4、VSCode 将自动在工作区根目录下创建 .vscode/GettingStarted.code-tour 文件。
三、添加首个导览步骤
每个步骤需绑定到具体代码行位置，并附带说明文本。VSCode 提供图形化方式快速插入步骤，确保定位精确且上下文可见。
1、打开待讲解的源文件（如 src/main.ts），滚动至需介绍的函数起始行。
2、右键点击目标行号区域，在上下文菜单中选择 CodeTour: Add Step Here。
3、在弹出的编辑框中输入说明文字，例如 这是应用的主入口函数，负责初始化状态管理器。
4、按 Enter 提交，该步骤将自动写入当前 .code-tour 文件并高亮显示在侧边栏中。
四、跨文件添加多步骤导览
真实导览常涉及多个文件间的逻辑流转。CodeTour 支持在单个 tour 文件中声明不同文件路径的步骤，实现模块化引导。
1、在已打开的 .code-tour 文件中，手动添加新步骤对象，格式如下：
2、在 steps 数组中插入 JSON 对象，包含 file（相对路径）、line（行号）和 description 字段。
3、例如添加：{"file": "src/utils/apiClient.ts", "line": 12, "description": "此处封装了所有后端请求拦截逻辑"}。
4、保存文件后，重启导览播放即可跳转至对应文件与行。
五、启动并播放导览
导览播放模式会高亮当前步骤所在代码行，并在编辑器右侧显示步骤说明卡片，支持暂停、跳转与退出，适合现场演示或异步学习。
1、点击 VSCode 右下角状态栏中的 Start Tour 按钮（或使用命令面板执行 CodeTour: Start Tour）。
2、选择已创建的 tour 文件（如 GettingStarted.code-tour）。
3、播放开始后，当前步骤对应的代码行将被绿色高亮，右侧出现说明面板。
4、点击面板底部的 Next 按钮进入后续步骤，或点击行号旁的播放控件直接跳转。
