如何利用 VSCode 的 CodeTour 扩展创建代码库的导览教程？-VSCode-PHP中文网

CodeTour通过在VSCode中创建交互式代码导览，将教程直接嵌入开发环境，提升团队协作与新人上手效率。它以分步形式引导用户浏览代码，结合Markdown说明，实现沉浸式、上下文感知的学习体验；相比传统文档，其优势在于与代码同步版本控制、动态更新、互动性强，且可通过模块化命名和目录结构管理多个导览；为避免内容过时或冗长，建议在PR审查中纳入导览维护，并定期检查，同时保持步骤简洁、聚焦核心逻辑，辅以设计思路与架构解析，增强知识传递深度。

如何利用 vscode 的 codetour 扩展创建代码库的导览教程？

CodeTour 是 VSCode 的一个强大扩展，它能让你在代码库中创建交互式的、分步的导览教程。简单来说，它就像是为你的项目编写了一个活生生的、可以在 IDE 里直接跟着走的 README，极大地简化了新成员的上手过程，或是帮助团队成员理解复杂功能。

解决方案

利用 CodeTour 创建导览教程的核心思路，是记录一系列的步骤，每个步骤都指向代码库中的特定文件、特定行，并配以详细的 Markdown 描述。这个过程其实比听起来要直观得多。

安装扩展： 首先，在 VSCode 扩展商店中搜索并安装 "CodeTour"。这是基础。
启动录制： 打开你的项目文件夹。按下
```
Ctrl+Shift+P
```
登录后复制
(或
```
Cmd+Shift+P
```
登录后复制
on Mac)，输入
```
CodeTour: Record Tour
```
登录后复制
并选择它。你会看到 VSCode 界面底部出现一个提示，表示正在录制。
添加导览步骤：
- 导航到你希望讲解的第一个文件和代码行。
- 在 VSCode 左侧的 CodeTour 视图中，点击
```
+
```
  登录后复制
  按钮，或者再次使用
```
Ctrl+Shift+P
```
  登录后复制
  输入
```
CodeTour: Add Tour Step
```
  登录后复制
  。
- 此时会弹出一个文本框，你可以在这里用 Markdown 语法编写该步骤的描述。例如，你可以解释这段代码的作用、为什么这样设计，或者它与哪些其他文件相关。
- 完成后，点击保存按钮或按下
```
Enter
```
  登录后复制
  。
- 重复上述步骤，移动到下一个文件和代码行，添加新的导览步骤。你可以随意切换文件、滚动代码，CodeTour 会记住你当前的位置。
保存导览： 当你认为导览内容足够了，再次按下
```
Ctrl+Shift+P
```
登录后复制
，输入
```
CodeTour: End Recording
```
登录后复制
。系统会提示你为导览命名，并选择保存位置。通常，它会生成一个名为
```
tour.json
```
登录后复制
的文件（或者一个
```
.tour
```
登录后复制
目录）并放置在你的
```
.vscode/
```
登录后复制
文件夹下。
分享导览： 最重要的一步是，将生成的
```
tour.json
```
登录后复制
或
```
.tour
```
登录后复制
目录提交到你的版本控制系统（如 Git）。这样，所有拉取了代码库的团队成员，只要安装了 CodeTour 扩展，就能直接在 VSCode 中看到并运行你的导览了。我个人觉得，这比口头解释或者写一堆文档要高效得多，毕竟代码就在眼前，上下文一目了然。

CodeTour 与传统文档相比，有哪些独特优势？

在我看来，CodeTour 之所以能脱颖而出，在于它打破了传统文档与实际代码之间的“次元壁”。

首先，沉浸式与上下文感知 是它最大的亮点。你不需要在浏览器和 IDE 之间来回切换，也不用费力地在文档中搜索代码片段，然后又回到 IDE 里定位。CodeTour 直接把你带到代码的现场，描述就在你眼前，鼠标一点，下一段代码就呈现在你面前。这种无缝的体验，对于快速理解一个新功能或一个复杂模块来说，简直是福音。我记得以前带新人，光是解释文件结构和关键代码位置，就要花掉半天时间，现在有了 CodeTour，他们可以自己跟着走一遍，效率提升了不止一倍。

其次，它动态且与代码库同步。传统的 README 或 Wiki 很容易过时，尤其是在快速迭代的项目中。但 CodeTour 的导览文件是作为项目代码的一部分进行版本控制的。这意味着，当代码发生变化时，如果导览也需要更新，它会成为代码审查（PR review）的一部分。这无形中就建立了一种机制，促使导览与代码保持一致。当然，这也不是说它能自动更新，维护依然需要，但至少它被放在了正确的位置，更容易被注意到和维护。

最后，它提供了一种互动式的学习体验。这不是被动地阅读，而是主动地“探索”。你可以随时暂停、回顾，甚至在导览的某个步骤中修改代码进行实验。这种互动性让学习过程更加引人入胜，也更容易记住关键信息。

如何更好地组织和管理多个 CodeTour 导览，以适应大型项目？

当项目变得庞大和复杂时，单一的 CodeTour 导览可能就不够用了，或者会变得过于臃肿。有效地组织和管理多个导览就显得尤为重要。

一个直接的策略是按模块或功能划分导览。例如，你可以为用户认证模块创建一个

authentication.tour

登录后复制

，为订单处理流程创建一个

order_processing.tour

登录后复制

。CodeTour 能够自动发现

.vscode/

登录后复制

.tour

登录后复制

文件或

.tour

登录后复制

目录。这意味着你可以在

.vscode/tours/

登录后复制

目录下创建多个子目录，每个子目录代表一个独立的导览，里面包含

tour.json

登录后复制

和对应的 Markdown 描述文件。这种结构让每个导览都保持专注和精简。

另一个我经常使用的方法是，利用

.tour

登录后复制

目录格式。而不是只生成一个

tour.json

登录后复制

文件，你可以让 CodeTour 创建一个像

feature-x.tour

登录后复制

tour.json

登录后复制

文件，以及每个步骤对应的 Markdown 文件（例如

step-1.md

登录后复制

step-2.md

登录后复制

）。这样做的好处是，导览的描述内容不再堆积在单一的 JSON 文件中，而是分散到独立的 Markdown 文件里，更易于阅读、编辑和管理，尤其是在描述内容较多的情况下。

此外，清晰的命名约定 也至关重要。给你的导览起一个描述性强、一目了然的名字，比如

Onboarding_CoreConcepts

登录后复制

、

FeatureX_DeepDive

登录后复制

、

BugFixY_PostMortem

登录后复制

。这样，团队成员在 CodeTour 视图中就能快速找到他们需要的导览。

百度智能云·曦灵

百度旗下的AI数字人平台

查看详情

虽然 CodeTour 目前不直接支持“导览中的导览”或嵌套结构，但你可以在一个导览的步骤描述中，引导用户去启动另一个相关的导览。比如，在一个介绍项目总览的导览中，某个步骤的描述可以写：“如果你想深入了解认证模块，请启动

authentication.tour

登录后复制

。”这是一种简单的逻辑跳转，可以帮助用户在不同主题之间切换。

在创建 CodeTour 导览时，有哪些常见的挑战及优化技巧？

在实际使用 CodeTour 的过程中，我遇到了一些挑战，也总结出了一些优化技巧。

挑战一：导览内容易过时。 这是所有文档的通病，CodeTour 也不例外。代码在不断演进，而导览却可能停留在旧版本。

优化技巧： 我通常会在代码审查（PR review）的 Checklist 中添加一项：“是否需要更新现有 CodeTour 导览，或创建新的导览？” 此外，定期（比如每个季度）安排一次“导览健康检查”会议，让团队成员一起运行和审查重要的导览，确保它们仍然准确。如果发现导览指向的代码已经不存在或发生重大变化，CodeTour 会在运行时给出提示，这是个很好的预警。

挑战二：导览内容过于冗长或不够聚焦。 有时，为了“面面俱到”，一个导览会变得非常长，包含太多细节，反而让用户失去耐心。

优化技巧： 保持每个步骤的简洁性。 专注于解释“为什么”和“是什么”，而不是“怎么做”的每一个微小细节。如果一个概念需要大量背景知识，考虑将其拆分为独立的、更小的导览。在步骤描述中，善用 Markdown 的标题、列表和代码块来组织信息，突出重点。例如：
```
### 核心服务入口 (`src/services/userService.ts`)

这个文件定义了用户管理的核心 API。我们在这里处理用户注册、登录和资料更新的业务逻辑。

**关键点：**
- `registerUser()`: 负责新用户创建，包含密码哈希和邮件验证流程。
- `authenticate()`: 验证用户凭据，并生成 JWT token。

**注意：** 实际的数据库操作在 `src/data/userRepository.ts` 中实现。
```
登录后复制
这种方式能让读者快速抓住要点，并知道去哪里寻找更深层次的细节。

挑战三：用户参与度不高，导览形同虚设。 即使创建了高质量的导览，如果团队成员不使用，那也是白费功夫。

优化技巧： 推广和鼓励使用。 在新员工入职培训中，将 CodeTour 作为强制性的第一步。在团队内部会议上，鼓励资深开发者创建导览来解释他们负责的复杂功能。甚至可以考虑“游戏化”一下，比如完成某个导览后，可以获得一些虚拟奖励或知识分享的荣誉。关键在于，让团队感受到 CodeTour 的实际价值，并将其融入日常工作流程。

挑战四：导览内容缺乏深度或过于泛泛。 有些导览可能只是简单地指向代码，而没有提供足够的背景或分析。