企业官网建设流程全解析

如何在 Void 中重新编译 React UI 层并正确命名外部导入

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

Void 的 React UI 层（侧边栏、设置、Quick Edit、diff 视图等组件）位于 src/vs/workbench/contrib/void/browser/react 目录。修改这里的.tsx源码后，需要重新编译才能生效，编译产物会输出到同目录下的out/。本文说明如何执行这次编译，以及外部导入的命名规则——导入路径没写对时，报错很难追踪，这是该目录文档里特别强调的坑。

前提条件：环境需要能运行node，且能通过npx调用scope-tailwind、tsup、nodemon（构建脚本全部通过npx拉起这些工具）。所有命令都在src/vs/workbench/contrib/void/browser/react/目录下执行，因为 README 中的node build.js是相对于该目录的。

执行编译：node build.js

进入该目录后运行一次完整构建：

node build.js

根据 build.js 的构建模式，这条命令按顺序做两件事：

1. 运行npx scope-tailwind ./src -o src2/ -s void-scope -c styles.css -p "void-"，从src/生成src2/目录；
2. 运行npx tsup，按 tsup.config.js 的配置把src2/下的入口编译成 ESM 产物，输出到out/。

构建结束时终端会打印✅ Build complete!（build.js 中的成功提示），产物目录为out/（README 明确说 "compile the React intoout/"）。

可选：watch 模式持续编译

开发时可以用 watch 模式代替反复手动构建：

node build.js --watch

-w是等效的简写。watch 模式的实际行为（见 build.js）：

• 如果src2/还不存在，先执行一次初始 scope-tailwind 构建创建它；
• 用nodemon监视src/下的ts,tsx,css文件，变化时重跑npx scope-tailwind ./src -o src2/ -s void-scope -c styles.css -p "void-"；
• 同时用npx tsup --watch持续编译，输出前缀分别为[scope-tailwind]和[tsup]；
• 输出中提到styles.css时，脚本会延迟 6 秒强制重写一次src2/styles.css（build.js 注释说明这是 "hack to refresh styles automatically"，用于让样式自动刷新）。

两个 watcher 都用 Ctrl+C 停止。

正确命名外部导入

这条规则直接决定构建能否按预期工作，README 原文是：

Make sure to add .js at the end of any external imports used in here, e.g.../../../../../my_file.js. If you don't do this, you will get untraceable errors.

原因在 tsup.config.js 的 external 判定上：

• noExternal配置为/^(?!\.).*$/，即所有不以.开头的包名（如react）都会被打包进产物，而不是保留为外部依赖；
• external配置为正则../../../*.js（即相对路径回退到上层、以.js结尾的导入）会被保留为外部引用，不重复实现，只是作为优化避免产物文件里再拷贝一份函数。

也就是说：想让某个相对导入保持外部（不打包进out/的产物），导入路径必须以.js结尾且匹配../../..这种相对形式。漏掉.js后缀时，构建不会给出清晰的报错，README 用 "untraceable errors" 描述这种失败现象——如果你发现运行时报错但构建本身没有明显失败，优先检查导入是否带.js后缀。

src/ 目录必须保持浅层

README 的第二条规则：

src/ needs to be shallow (1 folder deep) so the detection of externals works properly (see tsup.config.js).

src/下的组件目录（如sidebar-tsx/、void-settings-tsx/、quick-edit-tsx/）只允许一层文件夹深。原因是 external 正则固定为../../../*.js（恰好回退三层）：源码文件位于src/<组件目录>/内时，../../..正好回到 react 目录这一层。把文件再嵌套一层，相对导入就无法命中 external 正则，外部判定会失效。所以新增组件文件时，保持在src/下一层组件目录内即可，不要再往下建子目录。

结果验证与已知限制

验证编译是否成功，看两点：

1. node build.js结束时打印✅ Build complete!，且out/下生成了产物。tsup 配置中outbase: 'src2'，输出目录结构从src2开始保持层级；
2. 编译产物只包含src2/下各组件目录的index.tsx入口（void-editor-widgets-tsx、sidebar-tsx、void-settings-tsx、void-tooltip、void-onboarding、quick-edit-tsx、diff），其余文件不会成为独立入口。

配置层面的已知限制（均来自 tsup.config.js）：

• 产物格式固定为 ESM（format: ['esm']），splitting: false，平台目标为浏览器（platform: 'browser'），treeshake: true；
• injectStyle: true，即 CSS 会被打进输出文件；
• 入口指向的是src2/（scope-tailwind 的生成产物），所以不能跳过第一步直接跑 tsup——src2/不存在或过期时，应先执行一次完整node build.js让它重新生成；
• clean: false，out/不会被自动清空，旧产物文件可能与当前源码并存。

如果改动后out/里没有对应变化，检查顺序就是：构建是否报untraceable errors（回到导入后缀问题）→src/是否被嵌套得过深（external 判定失效）→ watch 模式下 nodemon/tsup 的输出是否正常滚动。

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