使用 CLI5 分钟阅读 · MARKDOWN ↗

配置与发现

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

项目文件

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

{
  "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。

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 检查结果。

传递到浏览器的元数据

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

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

代理与端口

原生模式的端口优先级依次是 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 进程模式，不会在原生服务器中创建独立监听器。

新增开发与构建配置

{
  "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。

自动发现

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

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

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

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

实现参考

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