从Code Runner到formulahendry：VS Code扩展开发实战与设计思路

有阵子在帮团队搭建内部工具链，我盯着 VS Code 插件市场翻来覆去地研究那些高下载量扩展，翻源码时突然意识到一件事：好几个我天天在用的工具，作者都是同一个人——formulahendry。如果你平时写代码也喜欢折腾编辑器，这个 GitHub 账号你大概率早就见过，只是没留意过。这个账号背后是微软开发者 Jun Han，他做出来的扩展插件覆盖了代码运行、Azure 服务、CSV 编辑这些完全不搭边的场景，而且几乎个个都是同品类里的头部选手。

这篇文章不是单纯给你介绍某个插件怎么用，而是想从“一个高产开源作者的项目集合”这个视角切入，拆解他是怎么做选型、怎么设计扩展、怎么让工具真正贴合开发者日常的。我会把他的代表作挨个捋一遍，挑出最能抄作业的核心思路，再结合我实际使用和读源码时的体会，聊聊如果你想自己上手开发 VS Code 扩展或者做类似的开源工具，应该从哪儿开始、避哪些坑。

你可以把它当成一份“开源项目鉴赏 + VS Code 扩展开发入门参考”来读。无论你是前端、后端、运维还是刚入门的学生，只要你每天都泡在编辑器里，这篇文章里的内容都会对你有实际价值。

1. 项目集合的整体设计与思路拆解

1.1 formulahendry 是谁，他的项目为什么值得研究

formulahendry 是微软开发者 Jun Han 在 GitHub 上的账号名。他长期从事 Azure 相关的开发工具工作，同时也是 VS Code 扩展开发者圈子里非常活跃的一员。如果你打开他的 GitHub 主页，会发现项目列表并不算长，但每个项目的 star 数都很能打，尤其 Code Runner 这个扩展，下载量早就过了几千万级别，在 VS Code 插件市场里常年霸榜。

我最早注意到这个账号，其实是因为一个很具体的痛点。那时候我经常要写一些临时脚本，Python、JavaScript、Shell 换来换去，每换一种语言就得在终端里手动敲命令，非常烦。后来装了 Code Runner，选中代码直接跑，所有问题都解决了。当时我只觉得这个插件好用，没想过去了解作者是谁。直到后来我开始研究 VS Code 扩展的架构，想找个足够流行、但代码量又不会大到看不完的项目当范本，才顺着 Code Runner 的仓库链接摸到了 formulahendry。

研究下来我发现，这个账号下的项目有一个很鲜明的共性：几乎所有扩展都聚焦在“开发者日常重复度最高、最琐碎、但又没人愿意好好做的场景”。跑代码、看 CSV、连 Azure、调整编辑器外观，这些功能听起来都不酷，但正因为接地气，使用频率才高得吓人。这恰恰是很多开源新手容易忽略的地方——总想做一个“平台级”“框架级”的大项目，结果半年过去连 README 都没写完。而 formulahendry 的路线是典型的“小切口、深挖掘、持续迭代”，每个工具解决一个具体问题，解决到极致。

1.2 从项目列表看选品逻辑：小工具为什么能爆发

我们来快速过一遍他比较有代表性的几个项目：

当然，这些项目的人气和维护状态不完全一样，有些早期项目如今更新频率已经很低了。但你会发现一个规律：他几乎没有跟风做过“某个框架的脚手架工具”或者“某种语言的语法高亮”这种已经塞满了同类产品的赛道，而是专挑“用编辑器的人一定会遇到、但往往只能用凑合办法解决”的场景。

拿 Rainbow CSV 举例。CSV 文件在代码仓库里随处可见，但绝大多数编辑器对 CSV 的支持就是纯文本，列一多，眼睛根本分不清谁是谁。Rainbow CSV 做的事情非常简单：把头行和每一列都映射成不同颜色，顺便加一个列对齐功能。这个功能没有任何高深技术，但它精准打在了痛点正中。我认识的数据分析师，几乎人手装了它，就是因为在预览百万行数据的时候，这个扩展能省下大量眼力。

1.3 为什么这套组合拳比单点突破更值钱

如果只维护一个爆款插件，那可能只是运气好。但能持续做出多个不同方向的爆款，说明作者有一套成熟的项目筛选和工程执行方法。这套方法我总结下来有两层：

第一层是“选对场景”。他选择的 CSV 预览、代码运行、Azure 登录，全是开发者工作流里绕不开的环节。这类场景的基本盘特别大，只要体验能比别人好一点点，扩散速度就非常惊人。相反，如果你做一个“给某种冷门语言写 LSP”的插件，即使做得再完美，受众就那几百个人，很难形成水花。

第二层是“做完之后认真运营”。我翻过这些仓库的 issue 和 release 记录，能明显感觉到维护者对用户反馈的响应速度很快。Code Runner 的迭代记录里，经常出现“修复某种语言路径含空格时无法运行”“添加对某新语言的支持”这种颗粒度极细的更新，每一版都在回答真实使用中产生的问题。这种反馈闭环，才是开源项目能活下来的核心。许多个人开发者死磕代码质量，却忽视 issue 治理，最后项目体验停留在“能用”而非“好用”，这就是差距所在。

所以我给你一个非常具体的建议：如果你想做自己的开源工具或项目，别一上来就建一个宏大的 repo，先把你在过去一个月里重复操作超过十次的手动步骤列出来，挑其中一个最烦的，做一个小而美的工具去消灭它。只要这个工具能真正用到你自己身上，你就会有持续打磨的动力，别人也能感受到这种真实感。

2. 核心细节解析与实操要点

2.1 Code Runner 到底做了什么，为什么它能这么火

Code Runner 是我觉得整个 formulahendry 生态里最值得解剖的项目。它最核心的能力是：支持超过四十种语言的代码直接运行，你不需要手动配置每种语言的编译运行命令，选中的代码块按一下快捷键，结果就会输出到 Output 面板。

这段描述听起来很简单，但真正用过的人知道它的贴心和烦躁并存。贴心在于它默认配置就覆盖了绝大多数主流语言，Java 的 class 路径问题、C++ 的编译参数、Python 的虚拟环境，这些最烦人的细节它都帮你处理了；烦躁在于如果你要自定义运行命令，或者你的环境比较特殊，配置起来会有一些学习成本。

咱们说点实在的，看一下它默认支持的代码运行方式，其实就是构造一条 shell 命令。比如你写了一段 Python，它会用类似 python -u file.py 的方式去执行；如果是 JavaScript，会用 node file.js；如果是 C++，它会在临时目录里调 g++ 编译，然后运行编译出来的可执行文件。这里的核心抽象是“每个语言对应一个 command 模板”，模板里可以带变量占位符，比如 $fileName 代表当前文件名，$dir 代表文件所在目录，$fileNameWithoutExt 代表不带扩展名的文件名。

我给你整理一个最小可运行的配置理解方式：

你如果自己也想做类似的工具，最关键的设计决策就是 executorMap 这种“配置即方案”的思路。它不针对每一门语言写死逻辑，而是把“执行命令”抽象成一段可替换的模板字符串，用户想改就改。这种扩展点设计让 Code Runner 能覆盖长尾语言——只要你想跑的语言能通过命令行运行，你就能自己加一条映射，不需要等作者发版。

2.2 扩展开发前你需要理解 VS Code 的扩展机制

如果你想照着做类似的扩展，得先理解 VS Code 扩展的基本构成。VS Code 扩展本质是一个 Node.js 项目，入口文件里导出 activate 和 deactivate 两个函数。activate 在扩展被激活时调用，你的所有命令注册、事件监听、状态栏按钮创建都放在这里。package.json 里的 contributes 字段用来声明扩展对编辑器 UI 的扩展点，比如命令、菜单项、快捷键、设置项，这些声明不需要写代码就能生效。

拿“添加一个右键菜单”来说。你只需要在 package.json 里这样声明：

json复制{
  "contributes": {
    "menus": {
      "editor/context": [
        {
          "command": "myext.run",
          "when": "editorHasSelection",
          "group": "navigation"
        }
      ]
    },
    "commands": [
      {
        "command": "myext.run",
        "title": "运行选中代码"
      }
    ]
  }
}

然后在扩展代码里注册对应命令：

javascript复制const vscode = require('vscode');

function activate(context) {
  const disposable = vscode.commands.registerCommand('myext.run', () => {
    const editor = vscode.window.activeTextEditor;
    if (!editor) return;
    const selection = editor.selection;
    const text = editor.document.getText(selection);
    // 在这里处理 selected text
    vscode.window.showInformationMessage(`选中的代码是: ${text.substring(0, 50)}`);
  });
  context.subscriptions.push(disposable);
}

function deactivate() {}

module.exports = { activate, deactivate };

这段代码里有两个地方值得注意。第一个是 context.subscriptions.push()，这是 VS Code 扩展里最基础的生命周期管理方式，所有你创建的注册对象都应该 push 到 subscriptions 里，这样扩展被卸载时才能自动释放资源。第二个是 when 条件，它决定了命令什么时候可见，editorHasSelection 表示只有编辑器里有选中文本时才显示菜单项，这种细节对用户体验的提升非常大。

2.3 README 和展示页的艺术：开源项目的门面工程

研究 formulahendry 的项目时，我意识到他的 README 写得非常有讲究。每个扩展的 README 开头都用一句话说明“这是什么”和“怎么装”，然后是 GIF 动图演示效果，最后是完整的配置项表格。这种结构看起来简单，但很多开发者包括我自己都容易忽略。

我说句可能得罪人的话：代码写得再好，README 写得烂，项目传播度也会大打折扣。GitHub 上的用户第一眼看到的是 README，不是源码。一个没有动图、没有快速开始指南的 README，会让 90% 的潜在用户直接关掉页面。而 formulahendry 的仓库，几乎每个都能让你在三十秒内搞清楚这工具长什么样子、能解决什么问题。

具体来说，写 README 时你可以参考这个四段式框架：

1. 首屏一句话定位：第一段话必须说明“这个工具是什么、解决什么问题”。比如 Code Runner 的定位就是“Run C, C++, Java, Python, JavaScript... code in one click”。
2. 效果展示优先：放一个大的 GIF 动图，演示核心操作路径。人脑对动态图像的接受速度远快于文字说明。
3. 快速开始步骤：给出最简单的三步上手方式，比如安装、配置、运行，不要一上来就铺开所有配置项。
4. 详细配置放后面：配置项说明用表格整理，每一项给默认值和含义，方便用户快速检索。

这个框架不限于 VS Code 扩展，任何开源项目都可以照用。我自己后来给公司内部工具写文档时，就是照这个结构改的，同事反馈找东西方便多了。

3. 实操过程与核心环节实现

3.1 从零开始搭建一个 VS Code 扩展开发环境

如果你看完前面的内容，决定自己动手做一个小扩展，这一节我按实际顺序给你捋一遍完整流程。先说环境准备，三样东西：Node.js（建议 18 以上）、VS Code、以及官方脚手架工具 yo 配合 generator-code。

打开终端，执行：

bash复制npm install -g yo generator-code

然后找一个工作目录，运行：

bash复制yo code

这一步会问你几个交互问题：你想创建哪种扩展类型（New Extension 就是最普通的 TypeScript 扩展）、扩展的名称、标识符、描述、是否初始化 git 仓库等。选完之后，它会自动生成一个标准的项目结构。

生成的目录下会有这些关键文件：

生成完项目后，直接在 VS Code 里打开这个目录，按 F5 会弹出一个新的“扩展开发宿主”窗口。这个窗口里加载的就是你正在开发的扩展，所有 console.log 都会输出到原窗口的调试控制台。这是调试扩展最常用的方式，改完代码后在宿主窗口里执行 Developer: Reload Window 就能热加载。

3.2 复刻 Code Runner 的最小核心：运行选中代码并捕获输出

现在我们来手动实现一个“只支持 Python 和 JavaScript 的最小版 Code Runner”，目的是跑通整个链路，你再扩展其他语言就很容易了。

先修改 package.json，在 contributes.commands 里添加运行命令，并注册一个快捷键：

json复制"contributes": {
  "commands": [
    {
      "command": "minirunner.run",
      "title": "Mini Runner: Run Code"
    }
  ],
  "keybindings": [
    {
      "command": "minirunner.run",
      "key": "ctrl+alt+r",
      "mac": "cmd+alt+r"
    }
  ]
}

然后在 src/extension.ts 里实现核心逻辑：

typescript复制import * as vscode from 'vscode';
import { exec } from 'child_process';

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand('minirunner.run', () => {
    const editor = vscode.window.activeTextEditor;
    if (!editor) {
      vscode.window.showWarningMessage('没有打开任何文件');
      return;
    }

    const document = editor.document;
    const languageId = document.languageId;
    const text = editor.document.getText(editor.selection); // 若没有选中，则取全文
    const code = text && text.length > 0 ? text : document.getText();

    const tmpFile = writeToTempFile(code, languageId, document.fileName);

    let command: string;
    if (languageId === 'python') {
      command = `python -u "${tmpFile}"`;
    } else if (languageId === 'javascript') {
      command = `node "${tmpFile}"`;
    } else {
      vscode.window.showErrorMessage(`暂不支持 ${languageId} 语言`);
      return;
    }

    exec(command, (error, stdout, stderr) => {
      const outputChannel = vscode.window.createOutputChannel('Mini Runner');
      outputChannel.show(true);
      outputChannel.append(stdout);
      if (error) {
        outputChannel.append(stderr || error.message);
        outputChannel.append(`\n[退出码: ${error.code ?? '未知'}]\n`);
      }
    });
  });

  context.subscriptions.push(disposable);
}

function deactivate() {}

这里我特意省略了 writeToTempFile 的实现，因为它涉及文件系统操作和随机命名，不同平台路径处理有差异。你只要明白核心思路：把要执行的代码先落成一个临时文件，再调用系统命令运行这个文件。这一步保证了你传入 exec 的是一条完整、可解析的命令。

关于这个实现有几点值得深聊。首先是 createOutputChannel——如果你按前面的代码直接用 console.log，输出只会在调试控制台里看到，普通用户打开扩展是看不到任何后果的。用 OutputChannel 才能让用户像看到 Code Runner 那样，在“输出”面板里看到程序结果。这是新手最容易踩的坑。

其次是“命令注入”问题。如果你直接把代码内容拼进 shell 命令，一旦代码里包含反引号、分号、$() 这类字符，可能会被 shell 解释成新命令，造成安全风险。更稳妥的做法是把代码写入临时文件，然后在命令行里只传文件名。这个思路在你以后开发任何执行类工具时都要坚持。

3.3 上线发布前必须做的几件事

很多人以为扩展做完本地能用就能发布了，实际上 VS Code 扩展市场对发布包有严格的校验。你需要安装 vsce 命令：

bash复制npm install -g @vscode/vsce

然后在项目根目录执行：

bash复制vsce package

如果 package.json 里有 README 缺失、仓库地址未填、版本号格式错误等问题，这步都会报错。打包成功后，会生成一个 .vsix 文件，你可以把这个文件直接发给同事，在 VS Code 扩展面板里选择“从 VSIX 安装”。真要上架市场，需要用 Azure DevOps 的流水线配置发布令牌，然后执行 vsce publish。这部分流程官方文档写得很详细，我不展开，但我不建议你在没有把扩展的 README、图标、许可证都补全之前就去 publish，审核体验会很煎熬。

发布前还有一件事：自动化测试。VS Code 官方推荐的测试方案是 @vscode/test-electron，它可以启动一个测试版的 VS Code 实例，在你的扩展代码里跑单元测试和集成测试。虽然搭建起来有点繁琐，但如果你打算长期维护，这步一定不能省。formulahendry 自己就专门写了 vscode-extension-tester 这个工具去做 UI 层的自动化测试，由此可见他对测试的重视程度。

3.4 用社区资源提升开发效率

开发扩展时很多基础设施不需要从零写。官方提供的 vscode npm 包是必须引入的，它包含了所有扩展 API 的类型定义。除此之外，我建议你关注这几个方向：

• vscode-extension-tester：如果你要做 UI 自动化测试，这个库能帮你操作宿主窗口，模拟点击、输入、断言菜单项，省去自己写一堆 selenium 逻辑的麻烦。
• @types/vscode：TypeScript 类型定义，开发时能获得完整的代码提示。
• ESLint + Prettier：代码规范不用多说了，开源项目没有这两个，issue 区会被格式问题占满。
• GitHub Actions：在 .github/workflows 里写一个自动打包和发布的工作流，每次打 tag 后自动跑测试、构建、发布。这能保证每个版本的发布流程一致，避免手忙脚乱。

用我自己的体会说，这些基础设施可能要花掉你整个项目 30% 的时间，但它们决定一个项目“能不能被别人接手”。formulahendry 的项目能够长期维护，很大程度上就是这些工程化细节做得好。

4. 常见问题与排查技巧实录

4.1 Code Runner 运行没反应的排查思路

我经常在社区里看到有人问：装了 Code Runner，按快捷键怎么没反应。这种问题 80% 跟扩展本身无关，而是环境变量或者语言路径的问题。我整理了一个排查速查表，你在遇到同类问题时可以按顺序检查：

这些排查思路放到你自己开发的工具上也通用。尤其是“先确认命令本身能在终端跑通”这条，可以帮你避免在扩展代码里找半天 bug，最后发现是系统环境问题。我后来写任何执行类工具的默认动作都是：把最终拼出来的命令打印出来，复制到终端里手动执行一次。这一步能排除至少一半的疑难杂症。

4.2 扩展开发中常见的权限与生命周期问题

如果你开始写自己的扩展，下面几个问题几乎一定会遇到。

第一个是权限问题。VS Code 扩展运行在 Node.js 进程中，它和普通的 Node 程序一样受系统用户权限限制。如果你的扩展需要读写某些系统目录，或者要调用需要管理员权限的命令，可能会失败。但请注意，不要轻易在扩展里用 sudo 或者提权操作，这既危险又会在不同平台上行为不一致。更好的做法是明确提示用户手动执行一次提权操作，然后把结果告知扩展。

第二个是异步生命周期问题。VS Code 扩展的 activate 函数默认会在所有命令注册完成前完成，如果你在 activate 里执行了耗时的异步操作，比如下载远程资源，一定要用 vscode.window.withProgress 给用户展示进度，否则用户会以为扩展卡死了。而且，如果你的异步操作抛异常没有被 catch，整个扩展的激活会失败，所有命令都会失效。

第三个是“命令未注册”问题。调试时偶尔会看到 command 'xxx' not found 的报错。这通常是 package.json 里声明了命令，但模板代码里没有调用 registerCommand，或者扩展激活失败。排查方法是在宿主窗口里打开命令面板，执行“Developer: Toggle Developer Tools”，看 Console 里是否有报错信息。

4.3 如何从开源项目里高效读源码

最后分享一个方法论层面的经验。很多人拿到 Code Runner 这类源码后，想学又不知道从哪儿切入，一头扎进逐行阅读，结果看得头昏脑涨。我的建议是带着问题读源码，按这四个层级递进：

1. 先跑起来：把项目 clone 到本地，按 README 在本地调试模式跑通，观察它的行为和文件结构。
2. 看 package.json：这个文件就像地图，它告诉你扩展注册了哪些命令、监听哪些事件、依赖哪些库。把这个文件看懂了，整个扩展的功能清单就出来了。
3. 找激活函数：activate 是入口，看它把哪些功能串了起来，每个命令注册对应的函数是哪个。你不用管每个函数的内部实现，先建立“命令到函数”的映射关系。
4. 挑一个你最关心的功能深入：比如 Code Runner 的 runCode 函数，看它如何选择执行器、如何捕获 output、如何处理错误。看完一个完整链路后，你对整个项目的理解深度会远超扫读十遍。

这套方法不光适用于 VS Code 扩展，读任何中型代码库都有效。很多开发者焦虑自己看不懂大型开源项目，其实就是没找到入口，被一层层抽象吓住了。记住，你是来学思路的，不是来背代码的。看懂一个小功能从触发到完成的完整路径，比看过 5000 行源码更有价值。

5. 项目背后的延伸思考与个人经验

5.1 “小工具大流量”背后的长期价值

研究 formulahendry 的这段时间，我反复在想一个问题：为什么有些人的工具能成为经典，而另一些人做了很多功能丰富的项目却始终没人用。我的答案可能有点反直觉——成功的小工具，不是因为功能多，而是因为它节省了用户每一次操作里最小的那一点点时间，但这个动作被千万人重复了无数次。

Code Runner 省掉的是“打开终端、输入命令、切换目录”这三个动作，单次可能只要十秒。但一个重度用户一天可能要跑几十次代码，一年下来就是几十个小时。当一个工具能把几十个小时从你的工作里拿掉，你一定会对它形成肌肉记忆。开发者也因此获得了持续维护的回报。这就是小工具的大流量逻辑。

如果你现在正在纠结做什么开源项目，我的建议是别再想“做什么能火”，而是认真记录自己这周的重复操作。每当你发现自己第五次在终端里敲同一串命令时，停下来想一想：这段操作能不能变成一键？如果当时没人做这件事，那你就可以做。

5.2 我踩过的坑和总结出的实操心得

我自己在参考 formulahendry 的项目做内部工具时，踩过不少坑，挑三个最有代表性的说。

第一个坑是“在扩展里写死了路径”。当时我开发一个调用内部编译器的工具，为了省事，直接把编译器的绝对路径写进了代码里。结果同事的机器上路径不一样，只能尴尬地现场改代码。后来我把路径挪到配置项里，给了一个默认值，最后演示时顺利通过。这个教训现在成了我的红线：任何环境相关的东西都要做成可配置，绝不允许硬编码。

第二个坑是“忽略错误处理”。初版扩展只管正常流程，一旦编译命令出错，终端窗口一闪而过，用户根本不知道发生了什么。后来我学 Code Runner 的做法，把错误信息完整输出到一个 OutputChannel，并保留退出码。这个问题解决后，同事的反馈率直线下降，因为他们至少知道去哪里看报错。

第三个坑是“测试跟不上”。我早期的扩展完全没有自动化测试，每次改动都手动打开 VS Code 点点点，改到后面自己也搞不清楚有没有弄坏别的功能。后来搭建了 @vscode/test-electron 集成测试环境，把核心流程的冒烟测试跑起来，才算是真正解放了双手。这件事我后悔没早点做。

5.3 后续可以怎么继续扩展

说回 formulahendry 的项目风格。他的扩展大多已经非常成熟，功能迭代空间其实不大，但如果你愿意观察，会发现还有一个方向被很多人忽视——扩展之间的组合使用。比如 Code Runner 负责跑脚本，Rainbow CSV 负责看数据，Markdown Mermaid 负责画图，当一个工作流涉及这几个工具的配合时，整体效率会非常高。你不一定需要自己写一个大而全的平台，把现成的小工具用脚本或命令行串起来，往往就能解决复杂问题。

对我个人而言，研究这个账号的最大收获，是真正理解了“工具开发”这一行的核心逻辑：不必追求宏大叙事，也不必绞尽脑汁做一些听起来酷炫但没人用的功能。开发者日常遭受的痛，就是你最好的产品说明书。把最琐碎、最平凡的那件事做扎实，时间会回馈你。

如果你也想做一个类似的项目，就从今天最让你烦躁的那个操作开始吧。