# 配置与发现

wu.config.json 中实际读取的字段、端口、命令和挂载元数据。

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


<span id="archivo-de-proyecto"></span>

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

## 项目文件

命令在工作目录查找 `wu.config.json`。没有全局 `--config` 选项，也没有 `wu config` 命令。路径相对于执行 CLI 的根目录解释。

```json
{
  "name": "conocimiento",
  "version": "1.1.0",
  "shell": {
    "dir": "shell",
    "framework": "astro",
    "port": 4321,
    "dev_cmd": "npx astro dev",
    "build_cmd": "npx astro build"
  },
  "apps": [
    {
      "name": "busqueda",
      "dir": "mf-busqueda",
      "framework": "react",
      "port": 5001,
      "dev_cmd": "npx vite",
      "build_cmd": "npx vite build"
    },
    {
      "name": "explorador",
      "dir": "mf-explorador",
      "framework": "vue",
      "port": 5002
    }
  ],
  "proxy": {
    "port": 3000,
    "open_browser": false,
    "/api": {
      "target": "http://127.0.0.1:8080",
      "rewrite": true,
      "cors": false
    }
  },
  "shared": ["react", "react-dom/client"],
  "security": {
    "enabled": true
  }
}
```

`version` 是配置元数据。可执行文件仍使用 `main.zig` 编译时确定的版本；编辑该字段不会更新 CLI。

<span id="shell-y-aplicaciones"></span>

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

## Shell 与应用

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| `shell.dir` | `shell` | 宿主目录 |
| `shell.framework` | `vanilla` | 选择 shell 的处理方式 |
| `shell.port` | `4321` | Vite 模式的进程端口 |
| `shell.dev_cmd` | 空字符串 | Vite 模式的 shell 命令 |
| `shell.build_cmd` | 空字符串 | 根据框架回退到 Astro、Next 或 Vite |
| `apps[].name` | 空字符串 | 目录中的应用标识符 |
| `apps[].dir` | 空字符串 | 本地目录及 overrides 的键 |
| `apps[].framework` | `vanilla` | 选择编译器或模板 |
| `apps[].port` | `0` | Vite 模式的应用端口 |
| `apps[].dev_cmd` | `npx vite` | 旧版开发命令 |
| `apps[].build_cmd` | `npx vite build` | 构建命令 |

解析器只接受实际使用的字段，不像严格 schema 那样验证完整拓扑；许多类型不正确的值会保留默认值。请明确声明名称、目录和端口，并通过 `wu info` 检查结果。

<span id="metadatos-que-llegan-al-navegador"></span>

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

## 传递到浏览器的元数据

| 各应用的字段 | 值与含义 |
| --- | --- |
| `fullBleed` 或 `full_bleed` | 布尔值，供 shell 决定是否给予全宽布局 |
| `domOwnership` 或 `dom_ownership` | `wu`、`app` 或 `light` |
| `nativeShadow` 或 `native_shadow` | 可选旧版别名；建议明确声明所有权 |
| `grants` | 宿主允许授予的能力上限列表 |
| `compatibility` | `strict` 或 `v2` |

这些字段会进入开发目录和构建结果。宿主授予 grant 不会替代 `wu.json` 中相应的权限申请。`fullBleed` 表达布局偏好，shell 在安排容器时必须读取并处理它。

<span id="proxy-y-puertos"></span>

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

## 代理与端口

原生模式的端口优先级依次是 `wu dev --port`、`proxy.port`、3000。浏览器打开行为的优先级是 `--open` 或 `--no-open`，其次 `proxy.open_browser`，后者默认为 `true`。

`proxy` 中每个以 `/` 开头的键定义一条规则。值可以是目标 origin 字符串，或包含 `target`、`rewrite` 和 `cors` 的对象。`rewrite: true` 移除前缀，例如把 `/api/users` 转发为 `/users`。`cors` 为可选项。

当前代理支持 `http://` origin，拒绝 TLS/`https://`、凭据和歧义目标。不要把含路径的 URL 当作 origin 声明。`shell` 和 `apps` 的端口属于 Vite 进程模式，不会在原生服务器中创建独立监听器。

<span id="opciones-nuevas-de-desarrollo-y-build"></span>

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

## 新增开发与构建配置

```json
{
  "dev": { "allowedHosts": ["mi-tunel.example.com"] },
  "build": { "keepPreviousBuilds": 2 },
  "security": { "upgradeInsecureRequests": false }
}
```

`dev.allowedHosts`（`allowed_hosts`）扩展 Host、CORS 和 WebSocket 允许的主机，不改变监听接口。`build.keepPreviousBuilds`（`keep_previous_builds`）保留历史构建的哈希文件，默认为 `2`。`security.upgradeInsecureRequests`（`upgrade_insecure_requests`）显式设置 CSP 指令；缺省时，若 `hsts` 为 `off` 或配置中存在 HTTP 来源，WU 会省略该指令。

重新加载配置时会保留 grants、清单模式和布局设置。新增应用会加入路由器及监听器；无内容变化的保存不会强制刷新。`./mf-a` 或 `mf-a/` 目录被规范化为 `mf-a`。

<span id="descubrimiento-automático"></span>

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

## 自动发现

缺少配置文件时，部分命令会检查直接子目录，识别项目特征和依赖。只有名称恰好为 `shell` 的目录会成为 shell，其他候选目录视为微应用。

自动发现识别导入的适配器和精确依赖名称：不会将 Preact 误识别为 React，并能检测 Qwik/Stencil。它对目录排序，从 5001 起分配不与 shell 冲突的空闲端口，并遵循显式声明的端口。

检测依赖启发式规则，不能复现完整模板矩阵，也不能替代显式清单的意图。JSON 格式错误时，会报告错误并禁用发现，避免对意外拓扑执行操作。请修复文件后再继续。

CLI `1.2.0` 允许每个应用使用 `manifest: "define"`，并通过 `security.frameOrigins` 配置远程 iframe。frame 源只进入 `frame-src`，不会允许宿主脚本或连接。目录导航过滤不会阻止 fetch 读取。见 [远程应用](/zh-cn/docs/framework/remote-apps/) 与 [构建](/zh-cn/docs/cli/build/)。

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

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

## 实现参考

- `wu-cli/src/config/config.zig`
- `wu-cli/src/config/discovery.zig`
- `wu-cli/src/runtime/allowed_hosts.zig`
- `wu-cli/src/runtime/dev/config_reload.zig`
- `wu-cli/src/runtime/handlers/proxy.zig`