使用 CLI5 分钟阅读 · MARKDOWN ↗

CLI 内部架构

Zig 分发器、配置、服务器、编译、HMR、所有权与贡献测试。

一次调用的执行路径

npm 启动器识别平台并执行二进制文件。main.zig 接收参数，将第一个 token 分发到命令模块。各命令决定如何解析其余参数，因此没有统一的全局选项语法。

项目命令通过加载器取得 WuConfig 结构。该配置把字符串保存在自己的 arena 中，并通过 deinit 释放内存，从而避免返回指向已释放 JSON 缓冲区的视图。目录发现是另一种配置来源，不是始终与显式文件合并的步骤。

模块索引

源码路径	职责
`src/main.zig`	命令分发、版本和 Zig 测试汇总
`src/cli/`	帮助、横幅、终端模式、菜单和提示
`src/config/config.zig`	解析与写入配置
`src/config/discovery.zig`	子目录项目识别规则
`src/config/deps.zig`	使用别名和本地工具链
`src/commands/`	使用场景与产物生成
`src/runtime/dev_server.zig`	监听器、路由、模块和重新加载桥接
`src/runtime/compile.zig`	选择编译器并连接守护进程
`src/runtime/compiler_daemon.js`	Node 编译器与消息分帧
`src/runtime/transform.zig`	重写 import、别名和 CSS
`src/runtime/hypervisor/`	监听器与前缀路由器
`src/runtime/security.zig`	路径验证和 HTTP 策略
`src/orchestrator/`	Vite 开发进程与监督管理
`src/util/jobobject.zig`	Windows 子进程生命周期

存在 src/proxy/server.zig 或 src/commands/test.zig，不能证明命令实际走这些路径。判断时应从分发器开始追踪调用，不要仅根据文件名推断能力。

src/runtime/dev/ 分离路由、文件、导入、CSS、环境、socket 和 HMR。module_graph.zig 维护身份及按导入者解析；project_fs.zig 限制文件访问。catalog.zig、semver.zig 和 json_doc.zig 集中处理版本、交集及清单写入。deploy.zig 和 build_cache.zig 实现事务式本地输出替换和构建复用。

服务器与编译器

请求通过 HTTP 进入，经验证后分配给应用或 shell，再解析为文件或依赖。编译产生 JavaScript，随后将 import 改写为服务器 URL。应用身份必须贯穿整个流程，才能正确解析其依赖、样式和工具链。

守护进程通过管道维护通信通道。请求包含标识符、编译类型、文件、loader、长度和应用目录。响应返回相同标识符，并传输代码或错误。长度用于确定消息边界，错误被压缩为协议中的单行。

协议按标识符多路复用请求。compile_pool.zig 管理带时限的多个守护进程，compile_warmup.zig 预编译导入；Angular 复用增量编译器。VFS、旧转换池和被禁用的原生 JSX 转换器已移除。

守护进程的标准输出专供协议使用。插件意外输出消息可能破坏帧对齐，因此守护进程会把多个 console 日志级别重定向到日志文件。父进程检查响应标识符，并在对话错位时重新启动通信。

监听器与路由器

hypervisor 在路由器中注册应用前缀，并监听项目目录，整合文件事件机制和内容缓存。需要注意其所有权关系：服务器按值返回后，指向内部字段的指针必须重新绑定到最终位置。bindRunning 用于处理这一生命周期关系。

服务器协调停止、关闭连接和守护进程。在 Windows 上，Job Objects 帮助确保子进程不会在所属进程结束后继续存活。这项功能需要在真实操作系统中测试；检查源码不等于已经观察到所有平台都正确清理进程。

构建并测试修改

zig build
zig build test --summary all
npm test

build.zig 定义编译和 Zig 测试步骤。npm test 执行 scripts/check-invariants.mjs 的不变量检查及 tests/*.test.cjs，验证启动器、守护进程协议和 doctor 退出状态等约定。请使用刚构建的二进制文件运行测试。测试摘要可确认实际执行和跳过的用例；验证生成应用仍需要浏览器测试。

main.zig 显式导入包含测试的模块；不变量检查测试聚合器和命令参考。npm run test:fuzz 测试 HTTP、WebSocket、路径、JSON、SemVer 和 import 解析器。发布使用 ReleaseSafe、校验和与可复现重建。

修改协议时，应测试分片消息、同一数据块中的多个请求、长错误信息和交叉标识符。修改应用骨架时，需要生成、编译并在浏览器中挂载。修改 HTTP 时，应测试路径、方法、缺失资源以及最终响应头。

实现参考

wu-cli/src/main.zig
wu-cli/src/runtime/dev/
wu-cli/src/runtime/compile_pool.zig
wu-cli/src/runtime/compiler_daemon.js
wu-cli/src/runtime/module_graph.zig
wu-cli/src/runtime/project_fs.zig
wu-cli/src/commands/deploy.zig
wu-cli/scripts/check-invariants.mjs
wu-cli/src/fuzz.zig