# 开发与重新加载

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

版本、变更与要求见 [Framework 3.2 与 CLI 1.0](/zh-cn/docs/guides/releases/)。


<span id="arrancar-el-servidor"></span>

<span class="section-anchor" id="section-1"></span>

## 启动服务器

```bash
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 结束。

<span id="qué-sirve-cada-ruta"></span>

<span class="section-anchor" id="section-2"></span>

## 各路由提供的内容

| 路由 | 内容 |
| --- | --- |
| `/` 和 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` 中的条目。

<span id="compilación-bajo-demanda"></span>

<span class="section-anchor" id="section-3"></span>

## 按需编译

浏览器请求文件时，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`，并在需要时重启守护进程。

<span id="controles-del-compilador"></span>

<span class="section-anchor" id="section-4"></span>

## 编译器控制

`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 类型。

<span id="cambios-y-recarga"></span>

<span class="section-anchor" id="section-5"></span>

## 变更与重新加载

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

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

<span id="modo-vite"></span>

<span class="section-anchor" id="section-6"></span>

## Vite 模式

```bash
wu dev --vite
```

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

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

<span id="túneles-y-variables-de-entorno"></span>

<span class="section-anchor" id="section-7"></span>

## 隧道与环境变量

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

```json
{ "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`、版本控制元数据和密钥仍被阻止；这些后缀不能用于读取私有文件。

<span id="diagnóstico-rápido"></span>

<span class="section-anchor" id="section-8"></span>

## 快速诊断

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

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-9"></span>

## 实现参考

- `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`