CodeTour插件可创建交互式项目导览：先安装插件，再新建.tour文件，支持跨文件跳转、代码块嵌入与行高亮，导览文件以相对路径保存于.vscode/codetours/并可提交Git共享。

如果您希望向团队成员或新加入的开发者清晰展示项目结构与核心逻辑，VSCode 的 CodeTour 插件可帮助您创建交互式、可执行的代码导览路径。以下是使用该插件构建项目介绍导览的具体操作方式：

本文运行环境：MacBook Air，macOS Sequoia。

一、安装并启用CodeTour插件

CodeTour 是一个由微软官方维护的开源扩展，需先在 VSCode 扩展市场中安装，之后才能创建和播放导览。该插件依赖 VSCode 的活动工作区与已打开的文件上下文，确保项目根目录已正确加载。

1、打开 VSCode，点击左侧活动栏的扩展图标（或按快捷键 Cmd+Shift+X）。

2、在搜索框中输入 CodeTour，找到由 Microsoft 发布的官方插件。

3、点击“安装”，安装完成后点击“重新加载”按钮使插件生效。

二、创建首个代码导览

导览以 JSON 文件形式保存在项目根目录下的 .vscode/codetours/ 子目录中，每个导览对应一个独立的 .tour 文件，支持多步骤、跨文件跳转与注释嵌入。

1、在 VSCode 中打开任意一个源码文件，例如 src/main.ts。

2、按下快捷键 Cmd+Shift+P，调出命令面板，输入并选择 CodeTour: Start New Tour。

3、在弹出的输入框中为导览命名，例如 Project Overview，回车确认。

4、此时编辑器右上角将出现浮动控件，点击“添加步骤”按钮，在当前光标位置插入第一条导览步骤，并填写说明文字。

三、添加跨文件导览步骤

真实项目介绍常需引导用户从入口文件跳转至配置、服务、组件等不同模块，CodeTour 支持显式指定目标文件路径与行号，实现精准导航。

1、在导览播放状态下，点击右上角“+”按钮，选择 Add Step to File...。

2、在文件选择器中定位到 src/config/index.ts，回车确认。

3、在弹出的行号输入框中填入 5，表示将光标自动定位至该文件第 5 行。

4、输入该步骤的描述，例如 此处定义了全局 API 基础地址与超时配置。

四、插入代码片段与高亮关键行

导览步骤支持内联代码块渲染与行范围高亮，便于聚焦关键逻辑，避免信息过载。该功能通过在步骤描述中使用特定 Markdown 语法触发。

1、在某一步骤的描述编辑框中，输入三重反引号包裹的代码块，例如：

const app = createApp(App);\napp.use(store);\napp.mount('#app');

2、在同一描述中，在代码块后追加行高亮指令：> Lines 2–3。

3、保存导览后播放，VSCode 将自动高亮显示第 2 至第 3 行，并渲染上方代码块作为上下文参考。

五、导出与共享导览文件

导览文件本质是结构化 JSON，可直接提交至 Git 仓库，供其他协作者同步加载。导览不依赖本地路径硬编码，所有文件路径均为相对于工作区根目录的相对路径。

1、在资源管理器中展开 .vscode/codetours/ 目录，找到刚创建的 Project Overview.tour 文件。

2、右键该文件，选择 Reveal in Finder（macOS）或对应平台的文件定位选项。

3、将整个 .vscode/codetours/ 目录添加至 Git 跟踪，并执行 git add .vscode/codetours/ 与 git commit -m "chore: add project introduction tour"。

# ai  # app  # markdown  # mac  # macbook  # 是一个  # 加载  # 如果您  # 跳转  # 运行环境  # 器中  # 选择器  # 该文件  # 框中  # 导览  # 行号  # js  # json  # 编码  # microsoft  # git  # macos  # vscode