Void 开源贡献实战指南：从开发者模式调试到本地构建与提交 PR
发布时间：2026/9/10 21:59:20 作者：尧图编辑部 阅读量：1,286
Void 开源贡献实战指南从开发者模式调试到本地构建与提交 PR【免费下载链接】void开源AI代码编辑器Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/voidVoid 是一款开源的 AI 代码编辑器其大部分业务代码集中在src/vs/workbench/contrib/void/目录。本文以仓库根目录的 HOW_TO_CONTRIBUTE.md 为骨架结合 VOID_CODEBASE_GUIDE.md 与真实源码结构完整讲解贡献者的工作流环境准备、开发者模式调试、终端构建、常见故障修复、本地可执行文件构建以及 Pull Request 规范帮助你从「能跑通代码」进阶到「能安全地提交改动」。一、Void 的贡献方式概览Void 官方在 HOW_TO_CONTRIBUTE.md 中列出了三种主要的参与途径完成路线图Roadmap上的任务官方维护了一份按功能模块组织的路线图贡献者可以从中挑选未完成项动手实现在社区频道提出建议功能想法、产品反馈可以直接通过社区渠道提交提交 Issue在仓库的 Issues 区提交新问题或 Bug 报告。在动手写代码之前官方强烈建议先通读 VOID_CODEBASE_GUIDE.md。这份指南专门解释了 Void 源码的组织方式阅读后你会发现仓库并没有第一眼看上去那么复杂。从当前仓库的实际目录结构看这一判断是成立的Void 的 AI 相关代码被清晰地收敛在src/vs/workbench/contrib/void/下并进一步按运行环境拆分为browser/、common/、electron-main/三个子目录。二、动手前必修Void 代码库速览HOW_TO_CONTRIBUTE.md 明确建议贡献者先读代码库指南下面摘取 VOID_CODEBASE_GUIDE.md 中最关键的几块内容作为后续开发调试的知识铺垫。2.1 VSCode 进程模型与目录约定Void 基于 Electron 构建Electron 运行两个进程main 进程负责内部逻辑和browser 进程这里的 browser 泛指 HTML 渲染环境而非特指网页浏览器。代码库中的目录名直接决定了代码运行在哪一侧browser/目录下的代码永远运行在 browser 进程可以使用window等浏览器 APIelectron-main/目录下的代码永远运行在 main 进程可以导入node_modulescommon/目录下的代码两个进程都能用但没有特殊导入权限。从当前仓库的 void 目录结构 可以印证这套约定common/下放着voidSettingsService.ts、modelCapabilities.ts、sendLLMMessageService.ts等跨进程共享的类型与纯逻辑electron-main/下则放着sendLLMMessage.impl.ts、sendLLMMessageChannel.ts等 main 进程实现。这里有一个关键约束browser 环境不允许直接导入node_modules。Void 采用了两种解决思路打包把原始 node_module 代码打包进 browser 侧React 就是这么处理的通道化把实现放在electron-main/再在 main 与 browser 之间建立通信通道channelsendLLMMessage就走这条路。从源码看第二种方案的具体落地是 sendLLMMessageChannel.ts 与 sendLLMMessage.impl.ts 的配合——main 进程发送 LLM 消息还能避免本地 provider 的 CSP内容安全策略问题。2.2 核心术语在 VSCode 生态中开发先对齐术语能省去大量困惑Editor你输入代码的编辑器。打开 10 个标签页仍然只有一个 editor标签页对应的是「model」Model文件内容的内部表示。多个 editor 可以共享同一个 model例如用Cmd\拆分编辑器时A.ts的 model 被两个 editor 共享这正是改动同步的机制URI每个 model 都对应一个 URI通常就是一个文件路径Workbench包裹所有编辑器、终端、文件树等 UI 的外壳Service只挂载一次的类单例。通过registerSingleton注册后即可在任何构造函数中通过Service注入使用Action / Command注册在 VSCode 上的函数用户可通过CmdShiftP命令面板调用代码内部也能通过 commandService 按 ID 调用。Void 用 Action 注册CmdL、CmdK等按键监听好处是用户可自行改绑键位。如果你想自己写一个带注册示例的最小服务/贡献点仓库里现成的模板是 browser/_dummyContrib.ts它演示了createDecorator定义服务接口、registerAction2注册带键位的 Action、registerSingleton注册单例服务、registerWorkbenchContribution2挂载工作台贡献点。文件注释里也写明了替换方式CmdShiftF全局替换DummyService为你的服务名即可。2.3 几条内部管线速览LLM 消息管线从侧边栏发消息到请求到达 provider 之间有一整套依赖链modelCapabilities.ts是其中需要随新模型发布而同步更新的重要文件Apply 机制分为快速 Apply基于 Search/Replace 块与慢速 Apply整文件重写。快速 Apply 会让 LLM 输出 ORIGINAL / / UPDATED格式的块从而在 1000 行的大文件上也能快速生效DiffZone 与 DiffAreaeditCodeService负责运行 ApplyLLM 调用 Edit 工具、用户提交CmdK走的是同一套代码只是 DiffZone 的覆盖范围不同——Apply 覆盖整个文件CmdK只覆盖较小的区域Void 设置服务voidSettingsService隐式依赖所有核心 Void 服务统一存储 provider、model 与全局设置其数据模型中包含FeatureNameAutocomplete/Chat/CtrlK/Apply、ModelSelection{providerName, modelName} 对、ChatModenormal/gather/agent等概念。提示构建管线相关的内容GitHub Actions、发布产物等维护在独立的构建仓库void-builder中仓库内不包含其源码本文不再展开外部链接。三、环境准备三大平台的先决条件Void 的贡献指南把环境准备按操作系统分成了三套请先对照自己的平台完成安装再进入开发者模式。3.1 Mac 平台需要Python和Xcode官方说明通常系统已默认安装。3.2 Windows 平台首先安装Visual Studio 2022推荐或VS Build Tools不推荐。如果机器上已有两者后续几步可能需要在两者上分别执行。安装时在Workloads工作负载选项卡勾选Desktop development with CNode.js build tools再到Individual Components单个组件选项卡勾选MSVC v143 - VS 2022 C x64/x86 Spectre-mitigated libs (Latest)C ATL for latest build tools with Spectre MitigationsC MFC for latest build tools with Spectre Mitigations最后点击 Install 等待完成。3.3 Linux 平台先全局安装 node-gypnpm install -g node-gyp然后按发行版安装系统依赖发行版系列安装命令DebianUbuntu 等sudo apt-get install build-essential g libx11-dev libxkbfile-dev libsecret-1-dev libkrb5-dev python-is-python3Red HatFedora 等sudo dnf install development-tools gcc gcc-c make libsecret-devel krb5-devel libX11-devel libxkbfile-develSUSEopenSUSE 等sudo zypper install patterns-devel-C-C-devel_C_C krb5-devel libsecret-devel libxkbfile-devel libX11-devel其他发行版可参考上游 VSCode 官方的 How to Contribute 页面外部链接此处不展开。另外仓库根目录存在 .nvmrc 文件内容锁定为20.18.2——这是 Void 官方指定的 Node 版本建议开发前确认当前 Node 版本一致详见下文「常见问题排查」。四、进入开发者模式Developer Mode这是贡献者修改并验证 Void 代码的标准方式全程无需打包成安装包改动后刷新窗口即可看到效果。完整步骤如下第 1 步克隆仓库git clone https://gitcode.com/GitHub_Trending/void2/void第 2 步安装依赖npm install第 3 步在 Void 或 VSCode 中初始化开发者模式打开克隆下来的项目按平台快捷键触发构建任务WindowsCtrlShiftBMacCmdShiftBLinuxCtrlShiftB初始化大约需要5 分钟当3 个 spinner 中有 2 个变成对勾时即表示完成。第 4 步打开 Void 开发者模式窗口Windows运行 ./scripts/code.batMac运行 ./scripts/code.shLinux运行 ./scripts/code.sh从源码看scripts/code.sh 会先调用node build/lib/preLaunch.js完成 Electron 下载、编译与内置扩展的准备随后设置NODE_ENVdevelopment、VSCODE_DEV1、VSCODE_CLI1等环境变量最后以.build/electron下的 Electron 可执行文件启动开发实例。第 5 步开始改代码并验证改动后必须刷新窗口才能看到变更在新窗口内按CtrlRMac 为CmdR重载或者按CtrlShiftP执行Reload Window。两个实用技巧隔离调试状态在第 4 步的命令后面追加--user-data-dir ./.tmp/user-data --extensions-dir ./.tmp/extensions这样你调试期间安装的扩展、修改的 IDE 设置都落在.tmp目录里想恢复原状只需删除.tmp文件夹正确终止构建脚本在构建脚本所在终端按CtrlD可彻底结束如果按CtrlC脚本会关闭但进程仍在后台运行。五、常见问题排查Common Fixes贡献指南汇总了一批高频报错及对应解法按顺序自查通常能解决 90% 的问题确认前置步骤全部完成见第三节各平台清单Node 版本必须是20.18.2即 .nvmrc 中锁定的版本。如果不想改动全局 Node 版本可以使用 nvm在仓库目录下依次执行nvm install和nvm usenvm 会自动读取.nvmrc安装并切换到对应版本Void 所在路径不能包含空格报错TypeError: Failed to fetch dynamically imported module检查所有 import 是否以.js结尾。这一约束在 React 侧有明确要求参见 browser/react/README.md——外部导入必须补.js后缀否则会得到难以追踪的错误遇到 React 相关错误尝试执行NODE_OPTIONS--max-old-space-size8192 npm run buildreact。该命令与 package.json 中的buildreact脚本对应它会进入 browser/react 目录执行node build.js把 React 代码编译到out/发现样式缺失等待几秒后重新加载窗口运行./scripts/code.sh时报错npm error libtool: error: unrecognised option: -static确认使用的是GNU libtool而非 BSD libtoolmacOS 默认是 BSD运行./scripts/code.sh时报错The SUID sandbox helper binary was found, but is not configured correctly执行下面两条命令修复 chrome-sandbox 权限后重试sudo chown root:root .build/electron/chrome-sandbox sudo chmod 4755 .build/electron/chrome-sandbox ./scripts/code.sh若仍有疑问可提交 Issue 寻求帮助。六、从终端构建 Voidnpm run watch开发者模式的CmdShiftB本质上是触发了 watch 构建任务如果你更习惯在终端操作可以跳过快捷键直接运行npm run watch构建完成的标志是在终端看到类似下面的输出[watch-extensions] [00:37:39] Finished compilation extensions with 0 errors after 19303 ms [watch-client ] [00:38:06] Finished compilation with 0 errors after 46248 ms [watch-client ] [00:38:07] Starting compilation... [watch-client ] [00:38:07] Finished compilation with 0 errors after 5 ms对照 package.json 的 scripts 配置可以理解这条命令的底层组成watch-client与watch-extensions分别通过node --max-old-space-size8192 ./node_modules/gulp/bin/gulp.js运行 gulp 的 watch 任务注意这里与第 5 步 React 报错时的--max-old-space-size8192是同一套内存扩容策略扩展与客户端各有一个 watch 进程两者都出现Finished compilation with 0 errors即代表热构建就绪。七、分发与本地可执行文件构建7.1 Void 的分发方式Void 官方通过官网和 Release 发布安装包。其构建管线是VSCodium 的一个 fork通过 GitHub Actions 自动产出各平台下载物完整的构建说明与「自动更新 / rebase」相关注意事项维护在独立的构建仓库void-builder中外部仓库此处不提供链接。如果你想完全掌控 Void 的构建管线用于内部使用可以研究void-builder仓库——但官方明确提醒这通常不推荐因为会带来可观的时间成本。7.2 构建本地可执行文件不推荐官方同样不推荐在本地构建完整可执行文件常规做法要么走上述分发管线获得带 VSCodium 优点的完整安装包要么直接用开发者模式本地运行快得多。但如果你确实需要可展开以下步骤前提已通过开发者模式完成初始化。构建全程约需25 分钟。按平台运行对应 gulp 目标Macnpm run gulp vscode-darwin-arm64 # 最常见Apple Silicon npm run gulp vscode-darwin-x64 # IntelWindowsnpm run gulp vscode-win32-x64 # 最常见 npm run gulp vscode-win32-arm64Linuxnpm run gulp vscode-linux-x64 # 最常见 npm run gulp vscode-linux-arm64gulp脚本在 package.json 中定义为node --max-old-space-size8192 ./node_modules/gulp/bin/gulp.js因此也可直接node --max-old-space-size8192 ./node_modules/gulp/bin/gulp.js vscode-darwin-arm64。输出位置产物会生成在void/仓库目录之外的文件夹中命名类似VSCode-darwin-arm64目录结构示意如下workspace/ ├── void/ # 你的 Void fork └── VSCode-darwin-arm64/ # 生成的输出八、Pull Request 规范代码改完并本地验证通过后按以下规则提交 PR请务必提交 Pull Request完成改动后直接发起 PR 即可无需预提交 Issue除非你创建的新功能可能横跨多个 PR否则不需要先建 Issue请勿使用 AI 代写 PR官方明确要求 PR 由贡献者本人撰写。附源码佐证速查贡献指南原文HOW_TO_CONTRIBUTE.md代码库指南强烈建议先读VOID_CODEBASE_GUIDE.mdNode 版本锁定.nvmrc内容为20.18.2开发者模式启动脚本scripts/code.sh、scripts/code.bat构建/构建脚本定义package.jsonbuildreact、watch-client、watch-extensions、gulpVoid 核心代码目录src/vs/workbench/contrib/void/含browser/、common/、electron-main/服务/贡献点注册模板browser/_dummyContrib.tsReact 侧构建说明browser/react/README.md按本文顺序完成环境准备 → 开发者模式调试 → 终端 watch 构建 → 本地验证 → 提交 PR即可安全、高效地参与到 Void 的开发中来。【免费下载链接】void开源AI代码编辑器Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 