企业官网建设流程全解析

Void 开源贡献实战指南：从开发者模式调试到本地构建与提交 PR

【免费下载链接】void开源AI代码编辑器，Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void

Void 是一款开源的 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等浏览器 API；
• electron-main/目录下的代码永远运行在 main 进程，可以导入node_modules；
• common/目录下的代码两个进程都能用，但没有特殊导入权限。

从当前仓库的 void 目录结构 可以印证这套约定：common/下放着voidSettingsService.ts、modelCapabilities.ts、sendLLMMessageService.ts等跨进程共享的类型与纯逻辑，electron-main/下则放着sendLLMMessage.impl.ts、sendLLMMessageChannel.ts等 main 进程实现。

这里有一个关键约束：browser 环境不允许直接导入node_modules。Void 采用了两种解决思路：

1. 打包：把原始 node_module 代码打包进 browser 侧，React 就是这么处理的；
2. 通道化：把实现放在electron-main/，再在 main 与 browser 之间建立通信通道（channel），sendLLMMessage就走这条路。

从源码看，第二种方案的具体落地是 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 上的函数，用户可通过Cmd+Shift+P命令面板调用，代码内部也能通过 commandService 按 ID 调用。Void 用 Action 注册Cmd+L、Cmd+K等按键监听，好处是用户可自行改绑键位。

如果你想自己写一个带注册示例的最小服务/贡献点，仓库里现成的模板是 browser/_dummyContrib.ts：它演示了createDecorator定义服务接口、registerAction2注册带键位的 Action、registerSingleton注册单例服务、registerWorkbenchContribution2挂载工作台贡献点。文件注释里也写明了替换方式：Cmd+Shift+F全局替换DummyService为你的服务名即可。

2.3 几条内部管线速览

• LLM 消息管线：从侧边栏发消息到请求到达 provider 之间有一整套依赖链，modelCapabilities.ts是其中需要随新模型发布而同步更新的重要文件；
• Apply 机制：分为快速 Apply（基于 Search/Replace 块）与慢速 Apply（整文件重写）。快速 Apply 会让 LLM 输出<<<<<<< ORIGINAL / ======= / >>>>>>> UPDATED格式的块，从而在 1000 行的大文件上也能快速生效；
• DiffZone 与 DiffArea：editCodeService负责运行 Apply，LLM 调用 Edit 工具、用户提交Cmd+K走的是同一套代码，只是 DiffZone 的覆盖范围不同——Apply 覆盖整个文件，Cmd+K只覆盖较小的区域；
• Void 设置服务：voidSettingsService隐式依赖所有核心 Void 服务，统一存储 provider、model 与全局设置，其数据模型中包含FeatureName（Autocomplete/Chat/CtrlK/Apply）、ModelSelection（{providerName, modelName} 对）、ChatMode（normal/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 C++
• Node.js build tools

再到Individual Components（单个组件）选项卡勾选：

• MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
• C++ ATL for latest build tools with Spectre Mitigations
• C++ MFC for latest build tools with Spectre Mitigations

最后点击 Install 等待完成。

3.3 Linux 平台

先全局安装 node-gyp：

npm install -g node-gyp

然后按发行版安装系统依赖：

其他发行版可参考上游 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 中初始化开发者模式

打开克隆下来的项目，按平台快捷键触发构建任务：

• Windows：Ctrl+Shift+B
• Mac：Cmd+Shift+B
• Linux：Ctrl+Shift+B

初始化大约需要5 分钟，当3 个 spinner 中有 2 个变成对勾时即表示完成。

第 4 步：打开 Void 开发者模式窗口

• Windows：运行 ./scripts/code.bat
• Mac：运行 ./scripts/code.sh
• Linux：运行 ./scripts/code.sh

从源码看，scripts/code.sh 会先调用node build/lib/preLaunch.js完成 Electron 下载、编译与内置扩展的准备，随后设置NODE_ENV=development、VSCODE_DEV=1、VSCODE_CLI=1等环境变量，最后以.build/electron下的 Electron 可执行文件启动开发实例。

第 5 步：开始改代码并验证

改动后，必须刷新窗口才能看到变更：

• 在新窗口内按Ctrl+R（Mac 为Cmd+R）重载；
• 或者按Ctrl+Shift+P执行Reload Window。

两个实用技巧：

• 隔离调试状态：在第 4 步的命令后面追加--user-data-dir ./.tmp/user-data --extensions-dir ./.tmp/extensions，这样你调试期间安装的扩展、修改的 IDE 设置都落在.tmp目录里，想恢复原状只需删除.tmp文件夹；
• 正确终止构建脚本：在构建脚本所在终端按Ctrl+D可彻底结束；如果按Ctrl+C，脚本会关闭但进程仍在后台运行。

五、常见问题排查（Common Fixes）

贡献指南汇总了一批高频报错及对应解法，按顺序自查通常能解决 90% 的问题：

1. 确认前置步骤全部完成（见第三节各平台清单）；
2. Node 版本必须是20.18.2（即 .nvmrc 中锁定的版本）。如果不想改动全局 Node 版本，可以使用 nvm：在仓库目录下依次执行nvm install和nvm use，nvm 会自动读取.nvmrc安装并切换到对应版本；
3. Void 所在路径不能包含空格；
4. 报错TypeError: Failed to fetch dynamically imported module：检查所有 import 是否以.js结尾。这一约束在 React 侧有明确要求，参见 browser/react/README.md——外部导入必须补.js后缀，否则会得到难以追踪的错误；
5. 遇到 React 相关错误：尝试执行NODE_OPTIONS="--max-old-space-size=8192" npm run buildreact。该命令与 package.json 中的buildreact脚本对应，它会进入 browser/react 目录执行node build.js，把 React 代码编译到out/；
6. 发现样式缺失：等待几秒后重新加载窗口；
7. 运行./scripts/code.sh时报错npm error libtool: error: unrecognised option: '-static'：确认使用的是GNU libtool而非 BSD libtool（macOS 默认是 BSD）；
8. 运行./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 寻求帮助。

六、从终端构建 Void（npm run watch）

开发者模式的Cmd+Shift+B本质上是触发了 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-size=8192 ./node_modules/gulp/bin/gulp.js运行 gulp 的 watch 任务（注意这里与第 5 步 React 报错时的--max-old-space-size=8192是同一套内存扩容策略），扩展与客户端各有一个 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 目标：

Mac

npm run gulp vscode-darwin-arm64 # 最常见，Apple Silicon npm run gulp vscode-darwin-x64 # Intel

Windows

npm run gulp vscode-win32-x64 # 最常见 npm run gulp vscode-win32-arm64

Linux

npm run gulp vscode-linux-x64 # 最常见 npm run gulp vscode-linux-arm64

gulp脚本在 package.json 中定义为node --max-old-space-size=8192 ./node_modules/gulp/bin/gulp.js，因此也可直接node --max-old-space-size=8192 ./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.md
• Node 版本锁定：.nvmrc（内容为20.18.2）
• 开发者模式启动脚本：scripts/code.sh、scripts/code.bat
• 构建/构建脚本定义：package.json（buildreact、watch-client、watch-extensions、gulp）
• Void 核心代码目录：src/vs/workbench/contrib/void/（含browser/、common/、electron-main/）
• 服务/贡献点注册模板：browser/_dummyContrib.ts
• React 侧构建说明：browser/react/README.md

按本文顺序完成环境准备 → 开发者模式调试 → 终端 watch 构建 → 本地验证 → 提交 PR，即可安全、高效地参与到 Void 的开发中来。

【免费下载链接】void开源AI代码编辑器，Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void