使用 CLI5 分钟阅读 · MARKDOWN ↗

开发与重新加载

原生服务器、Vite 模式、实际编译、路由与 Astro shell 的行为。

启动服务器

wu dev --port 3200 --no-open

默认模式为原生模式，在 127.0.0.1 打开 HTTP 监听器，以同一 origin 提供 shell 和微应用。此版本的参数解析器不提供 --host 选项。

选项	作用
`--port <n>`, `-p <n>`	原生模式的 HTTP 端口
`--native`	选择 Zig 服务器；默认模式
`--vite`	选择按应用监督进程
`--open`, `-o`	请求在原生模式打开浏览器
`--no-open`	禁止在原生模式打开浏览器

同时出现 --native 和 --vite 时，最后一个生效。端口值无法转换为 u16 时，不构成有效覆盖，将改用配置值。实际端口冲突会报告端口号，并以退出码 1 结束。

各路由提供的内容

路由	内容
`/` 和 shell 页面	shell 源码或其 Astro/Next 构建输出
`/mf-busqueda/src/main.tsx`	该微应用编译后的模块
`/@modules/<specifier>`	为浏览器解析的 npm 依赖
`/@wu/apps.json`	开发中的项目目录
`/@wu/client.js`	注入的重新加载客户端
`/__wu_ws`	用于重新加载的 WebSocket 通道
`/__wu_hmr`	备用 SSE 通道

这些路由属于服务器，不是应用业务端点。产品页面应避免占用这些前缀。解析时使用应用目录查找依赖，并应用 .wu-deps.json 中的条目。

按需编译

浏览器请求文件时，WU 解析文件、调用对应编译器，并将 import 改写为可加载的 URL。转换层处理 npm 导入、@/ 与 ~/ 源码别名，以及 CSS 导入。

Vue 和 Svelte 使用各自编译器，Solid 使用其转换器，Qwik 使用其优化器。Angular 保留增量 TypeScript 程序和 esbuild 上下文。TypeScript 与 JSX 需要项目的 Node 工具；旧版被禁用的原生 JSX 转换器已删除。

守护进程协议支持多路复用，进程池并行编译模块。缓存键包含编译器版本、锁文件、.wu-deps.json 和 tsconfig；更新后的首次运行会重新编译。日志位于 .wu-cache/wu-compiler.log。错误或超时返回带错误覆盖层的 HTTP 500，并在需要时重启守护进程。

编译器控制

WU_COMPILE_TIMEOUT_MS 设置编译时限，默认为 30000 毫秒。WU_COMPILE_WORKERS 设置守护进程数量，默认为 min(CPU, 4)，上限为 16。WU_COMPILE_PREFETCH=0 关闭 import 预编译。这些变量配置启动 wu dev 的进程。

依赖使用 esbuild 预打包到 .wu-cache/deps/，其带版本 URL 为不可变。项目文件和已编译模块使用 ETag 及 304 重新验证。静态文件支持 HEAD 和单个字节范围（206/416）；通过 fetch 或 import 属性请求的 JSON 保留 JSON MIME 类型。

变更与重新加载

监听器会纳入启动后创建的目录，并使用编号事件队列。每个模块具有独立版本：编辑会使该模块及直到应用入口的导入者失效。未更改模块保留实例；共享代码变更会重新挂载受影响的应用。事件丢失或服务器重启会触发完整刷新。局部状态能否保留取决于框架和更改内容。

Astro 或 Next shell 属于特殊情况：WU 提供 shell/dist/ 或 shell/out/。首次启动缺少 index.html 时会尝试构建，后续变更则先重新构建再刷新。初始构建失败时，微应用可能仍可访问，但 shell 会返回 404，直到其构建命令修复。

Vite 模式

wu dev --vite

该分支为 shell 和每个微应用分别创建进程，使用各自声明的 dev_cmd 和端口，并向每个命令添加 --port。应用使用本地工具链时，会尝试运行该应用的 Vite。

该分支接收配置，不接收为原生服务器计算的端口和浏览器打开选项。因此，wu dev --vite --port 3200 不会改变所有端口，也不会创建原生模式的统一监听器。需要检查项目特定工具链的行为时，可使用 Vite 模式。

隧道与环境变量

默认接受的 Host 为 localhost、*.localhost 和 IP 字面量。CORS 与 HMR 拒绝外部来源。使用隧道时，声明不带协议和端口的精确主机名；保存配置即可应用列表，无需重启。*.example.com 接受子域，不接受根域。避免对共享供应商使用通配符。

{ "dev": { "allowedHosts": ["mi-tunel.example.com"] } }

从 1.1.0 起，开发和原生构建中只有带 VITE_ 或 WU_ 前缀的 .env 键会进入 import.meta.env。私有键读取为 undefined 并产生警告。只迁移公开值：之前为 API_URL / import.meta.env.API_URL，之后为 VITE_API_URL / import.meta.env.VITE_API_URL。密钥应保留在后端。

文件、模块、sourcemap 和清单路由都会检查项目或包边界及符号链接。使用 ?raw、?import 或 ?inline 时，.env、版本控制元数据和密钥仍被阻止；这些后缀不能用于读取私有文件。

快速诊断

页面空白时，应查看首个失败的模块请求和浏览器控制台。除了服务器进程，还需检查 wu.json、注册名称、grants 和入口。编译错误请查看 WU 输出和守护进程日志。应用被跳过时，通常是配置中的目录不存在或重复。

实现参考

wu-cli/src/commands/dev.zig
wu-cli/src/runtime/dev/
wu-cli/src/runtime/compile_pool.zig
wu-cli/src/runtime/compile_warmup.zig
wu-cli/src/runtime/module_graph.zig
wu-cli/tests/dev-security.test.cjs
wu-cli/tests/dev-hmr.test.cjs
wu-cli/tests/dev-compile-concurrency.test.cjs
wu-cli/tests/dev-serving.test.cjs