VS Code 插件开发中文文档

# 开发插件

这个章节会详细地讲解如何插件的运行，调试和故障排除。这些技巧也同样适用于调试你从市场安装的问题应用。

# 创建你自己的插件

为了开发VS Code插件，VS Code本身提供了以下几个工具，帮你快速开发：

  • Yeoman生成器，用脚手脚创建一个插件
  • 智能补全——悬停和找到你需要的插件API
  • 编译Typescript（如果用Typescript实现的话）
  • 运行和调试插件
  • 发布插件

我们建议你用脚手架生成基础文件，Yeoman的yo code命令可以完成这个工作，生成器能极大地提升你的开发体验，我们在插件生成器里面有详细的步骤。

注意

以下部分假设你已经掌握了yo codeYeoman 插件生成器，和创建launch.json、task.json的基础知识。

# 运行和调试插件

按下F5，你就可以很轻松地调试插件了。这个命令会打开一个加载了你的插件的新窗口，插件输出的信息能在调试控制台里找到，在这个模式下你可以打断点、一步步地调试代码，在调试侧边栏或者调试控制台（用console方法输出才可以）检查变量。

根据插件的不同，你可能需要更多关于调试适配器或者语言服务器插件的相关教程：

# 编译Typescript

如果你的插件是Typescript实现的，那你首先就要把代码编译成Javascript。 编译过程的配置如下所示：

  • tsconfig.json定义了Typescript的编译选项。了解更多Typescript wiki或者Typescript语言章节
  • 当前Typescript编译器的版本在node_modules文件夹里面
  • API定义在node_modules/vscode中

运行插件前，Typescript编译器会被触发。.vscode/launch.json中的preLaunchTask属性定义了这项工作，在调试会话启动前会先启动这个配置好的任务。

如果你的插件在很久之前就编译好了，比如依赖于0.1.0ts版本，而2.0.0已经老早就出来了，那么通过下列步骤来升级你的插件：

// 访问 https://go.microsoft.com/fwlink/?LinkId=733558
// 查看更多关于tasks.json格式的内容
{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "npm",
            "script": "watch",
            "problemMatcher": "$tsc-watch",
            "isBackground": true,
            "presentation": {
                "reveal": "never"
            },
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

将下列设置添加到settings.json中

  // 关边tsc的自动检测任务，因为我们在添加了npm脚本
    "typescript.tsc.autoDetect": "off"
1
2

确保launch.json.中引用了正确的预运行任务：

"preLaunchTask": "npm: watch"
1

注意

Typescript编译器运行在watch模式下，所以任何文件变动都会自动编译

# 加载你的插件

你的插件会加载在插件开发环境的新窗口中。用extensionDevelopmentPath命令行也可以达到同样的效果，这个选项告诉VS Code去哪里查找新的插件：

code --extensionDevelopmentPath=_my_extension_folder
1

一旦插件环境加载完毕，VS Code就会把调试器附加上去，然后启动调试会话。

下面是按下F5之后的会发生的事情：

  1. .vscode/launch.json指示VS Code先运行一个叫做npm的任务
  2. .vscode/tasks.json定义了npm任务，其实就是npm run compile的脚本命令
  3. package.json定义compile为tsc -watch -p ./
  4. 然后会调用node_modules文件夹下的Typescript编译器，然后生成out/extension.js和out/extension.js.map
  5. Typescript编译成功之后，生成code --extensionDevelopmentPath=${workspaceFolder}进程
  6. 加载运行在扩展环境下的第二个VS Code实例，它会搜寻${workspaceFolder}下的插件

# 修改你的插件

你可以在VS Code状态栏的左侧观察Typscript编译器的进度，在状态栏中你也可以找到编译的错误和警告。当编译通过之后，你必须重启扩展开发环境才能查看到你的修改。重启扩展开发环境有两种可选的方式：

  • 在调试面板中按下重启
  • 在插件开发环境中按Ctrl+R（macOS：Cmd+R）

# 分析你的插件

你可以用Chrome DevTool内存和CUP分析工具分析你的插件。

跟我做：

  1. 在命令行中带上--inspect-extensions=<port>标识，启动你的VS Code，比如：code --inspect-extensions=9333
  2. 在VS Code的命令面板(Shfit + Cttl+ P)中选择并打开Developer: Toggle Developer Tools
  3. 在打开的DevTool中查看Console标签，找到Debugger listening on port 9333开头的chrome-devtools链接信息
  4. 打开你自己的Chrome浏览器，输入该链接，然后会进入DevTool提供的专用调试环境
  5. 使用内存和CPU分析器，了解内存和计算资源的使用情况

chrome-devtools

# 问题追踪

当你自己的的插件或者市场上的插件出现问题时，你可以参考这些建议进行问题追踪：

# 禁用插件，启动VS Code

通过--disable-extensions命令行，禁用VS Code会话中的所有插件。这个方式可以帮你逐步缩小问题范围——到底是插件问题，还是VS Code本身的问题。

code --disable-extensions
1

# 使用开发工具控制台

如果你安装的插件不能正常工作，第一步工作最好是先检查一下VS Code开发者工具的Console面板。插件作者可能在开发插件的时候已经添加了一些日志——VS Code 运行于Electron之上，所以你可以通过Chrome开发者工具获得有力的支持。

通过帮助>切换开发人员工具（Windows/Linux：Ctrl + Shift + I，macOS：Cmd + Shift + I）打开开发工具然后选择Console标签。试着运行插件的功能，检查Console的输出。你可以使用console.log输出各类信息以及VS Code扩展环境抛出的详细异常。

开发者小贴士

当你制作插件的时候，请为用户提供有用的日志信息，你给用户的信息越多，用户越能够独立地解决问题。好的日志也同样能帮你快速地找到真正的问题所在。

# 重装插件

有时候安装插件会失败或者报错，所以任何插件不能正常工作的时候，你都可以尝试卸载然后重装插件的方式来解决。VS Code提供了一个非常方便的命令Developer: Reinstall Extension，输入这串命令之后，你可以在下拉框里选择你要重装的插件，最后按照指示重载VS Code就好了。

# 查看插件的README

为了正常运行，有些插件会有一些其他的依赖，比如独立的语法检查器、编译器、自定义的配置文件等。因此在侧边栏插件中点击某个插件后显示的插件详情页面会非常有用，它就是插件的README，其中可能包含了插件的配置和使用方式。

# FAQ

问：我怎么在插件里使用VS Code新版本引入的API？

答：如果你想用最新的VS Code API，你可以在插件的package.json中的engines声明你想要用的引擎版本。

步骤如下：

  • 在package.json中的engines字段设置你的插件所需要的最低VS Code版本
  • 在package.json中添加postinstall脚本：
    "scripts": {
    "postinstall": "node ./node_modules/vscode/bin/install"
}
    1
    2
    3
  • 在你的插件根目录下输入npm install
  • vscode模块根据engine中声明的版本下载对应的vscode.d.ts
  • 回到VS Code，用代码补全验证是否出现了你想要的API提示

# 下一步

← 测试你的插件 →