VSCode 插件开发本地调试

Author: hewking
Labels: blog
Created: 2025-01-05T03:30:34Z
Link and comments: https://github.com/hewking/blog/issues/44

开发 VS Code 插件时，本地调试非常重要，可以帮助你快速发现和修复问题。以下是几种常用的 VS Code 插件本地调试方法，从简单到复杂依次介绍：

1. 重新加载窗口 (最简单)

• 适用场景： 修改了插件代码（例如修改了命令的实现、添加了新的功能），但没有涉及复杂的逻辑或需要断点调试的情况。
• 操作方法： 在 VS Code 中按下 Ctrl+R (Windows/Linux) 或 Cmd+R (macOS) 重新加载窗口。这将重新加载你的插件，使更改生效。
• 优点： 快速、简单。
• 缺点： 无法进行断点调试，不适用于复杂的调试场景。

2. 使用 VS Code 内置的调试功能 (推荐)

这是最常用和推荐的调试方法，可以进行断点调试、单步执行等操作。

• 准备工作：
  • 确保你的插件项目已经正确配置，并且可以正常运行。
  • 在需要调试的代码行设置断点。点击代码行号左侧的空白区域即可添加断点。
• 配置 launch.json 文件：
  • 在 VS Code 的“运行和调试”视图 (Run and Debug view) 中，点击“创建 a launch.json 文件”链接，或者手动在 .vscode 文件夹下创建 launch.json 文件。
  • 选择 “Extension” 环境。VS Code 会自动生成一个基本的配置。
• launch.json 文件示例：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Extension",
            "type": "extensionHost",
            "request": "launch",
            "runtimeExecutable": "${execPath}",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}"
            ],
            "stopOnEntry": false // 可选，设置为 true 将在插件启动时暂停
        },
        {
            "name": "Launch Tests", // 如果有测试
            "type": "extensionHost",
            "request": "launch",
            "runtimeExecutable": "${execPath}",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}",
                "--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
            ]
        }
    ]
}

• 开始调试：
  • 在“运行和调试”视图中，选择 “Launch Extension” 配置。
  • 按下 F5 或点击绿色的启动按钮开始调试。
  • VS Code 会打开一个新的扩展开发主机窗口，你的插件将在这个窗口中运行。
  • 当代码执行到断点时，程序会暂停，你可以查看变量的值、单步执行代码等。
• 调试命令：
  • F5：继续执行。
  • F10：单步跳过 (Step Over)。
  • F11：单步进入 (Step Into)。
  • Shift+F11：单步跳出 (Step Out)。
  • Shift+F5：停止调试。

3. 使用 console.log() 输出调试信息

• 适用场景： 简单的调试，不需要断点。
• 操作方法： 在你的插件代码中使用 console.log() 输出你需要的信息。
• 查看输出： 在扩展开发主机窗口中，打开“输出”面板 (View > Output)，选择 “Extension Host” 输出通道。
• 优点： 简单易用。
• 缺点： 不适用于复杂的调试场景，信息输出不够直观。

4. 调试 Webview (如果你的插件使用了 Webview)

如果你的插件使用了 Webview 来创建用户界面，你需要单独调试 Webview 的内容。

• 使用 Chrome DevTools：
  • 在扩展开发主机窗口中，打开 Webview。
  • 在 Webview 中右键单击，选择 “检查” 或 “Inspect”。
  • 这将打开 Chrome DevTools，你可以像调试普通的网页一样调试 Webview 的 HTML、CSS 和 JavaScript 代码。

5. 调试测试 (非常重要)

编写单元测试和集成测试是保证插件质量的重要手段。

• 配置 launch.json 文件（如上面的示例）： 配置 “Launch Tests” 配置项，指定测试入口文件。
• 运行测试： 在“运行和调试”视图中，选择 “Launch Tests” 配置，然后开始调试。

一些提示和技巧：

• 使用双显示器： 一个显示器用于编写代码，另一个显示器用于运行和调试插件，可以提高开发效率。
• 使用 stopOnEntry: true： 在 launch.json 文件中设置 "stopOnEntry": true 可以在插件启动时立即暂停，方便你进行初始化的调试。
• 阅读 VS Code 官方文档： VS Code 官方文档提供了详细的插件开发和调试指南，是学习的最佳资源。

通过以上方法，你可以有效地调试 VS Code 插件，提高开发效率和插件质量。记住，编写测试是保证插件可靠性的关键步骤。