# 配置与 manifest

shell 配置什么、wu.json 可以声明什么，以及 Framework 4 如何验证启动。

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


<span id="dos-documentos-con-distinta-autoridad"></span>

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

## 两份文档具有不同权限

`wu.init()` 配置属于 shell。`wu.json` 属于应用，从 `<url>/wu.json` 下载。manifest 请求资源；shell 决定可授予的权限上限。manifest 的任何字段都不能为自身授予权限。

```js
import { wu } from 'wu-framework';

await wu.init({
  sandbox: 'module',
  strictEvents: true,
  strictFallback: false,
  manifestPolicy: { imports: 'error' },
  apps: [{
    name: 'catalog',
    url: '/apps/catalog',
    framework: 'react',
    container: '#catalog-slot',
    keepAlive: false,
    grants: [
      { capability: 'store.read', resource: 'catalog' },
      { capability: 'events.emit', resource: 'catalog:selected' },
    ],
  }],
});
```

`container` 配置可由 `wu.app()` 使用的目标。显式调用 `wu.mount('catalog', '#catalog-slot')` 可以清楚地展示每次挂载的目标。

<span id="opciones-globales"></span>

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

## 全局选项

| 选项 | 初始值 / 行为 |
| --- | --- |
| `apps` | 包含 `name` 和 `url` 的配置列表 |
| `sandbox` | `module`；还支持 `strict` 和 `eval` |
| `strictFallback` | `false`；启用后允许失败的 strict 加载降级为 eval |
| `strictEvents` | 初始化时强制为 `true`，除非明确设置 `false` |
| `eventBus` | 总线设置；`strictEvents` 优先于 `strictMode` |
| `manifestPolicy.imports` | `error`；还支持 `warn` 和 `off` |
| `overrides` | 开发 URL 替换系统的设置 |
| `compatibility` | `strict` 配置档或显式迁移配置 |

`init` 合并并发调用，等待插件安装，注册应用，并在完成全部注册后验证 imports。初始化失败会回滚本次尝试创建的注册。成功初始化后，再次调用 `init` 会发出警告并结束：它不是用于热替换配置的 API。

`whenReady()` 返回解析为布尔值的 Promise。如果尚未启动 WU，则返回 `false`；如果启动尚未完成，则等待结果。`mount()` 已经会等待正在进行的 `init`。

<span id="manifest-completo-y-válido"></span>

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

## 完整有效的 manifest

```json
{
  "name": "catalog",
  "version": "1.2.0",
  "entry": "assets/catalog.js",
  "styleMode": "own-only",
  "wu": {
    "exports": { "ProductCard": "components/product-card.js" },
    "imports": [],
    "permissions": [
      { "capability": "store.read", "resource": "catalog", "required": true },
      { "capability": "events.emit", "resource": "catalog:selected" }
    ],
    "roles": ["catalog-reader"]
  },
  "metadata": {
    "description": "Explorador del catálogo",
    "routes": ["/catalog", "/catalog/:id"]
  }
}
```

允许的顶层字段为 `name`、`entry`、`wu`、`metadata`、`styleMode`、`version`、`folder` 和 `roles`。`wu` 内识别 `exports`、`imports`、`permissions`、`roles` 和历史字段名 `routes`，但 Framework 4 规范化会拒绝其中非空的路由。描述性信息请使用 `metadata.routes`。

`framework`、`sandbox`、`grants`、`domOwnership` 和 `keepAlive` 属于 shell 配置。额外字段不会被无条件接受：请将自定义元数据放入 `metadata`。

<span id="reglas-de-carga-y-validación"></span>

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

## 加载与验证规则

**真正的 404** 允许生成默认 manifest，其 `entry: 'index.js'`，权限为空。网络错误、500、无效 JSON 或将 HTML 页面作为 manifest 返回都会导致错误。这样可避免将服务器配置错误误判为应用没有 manifest。

| 限制 | 代码中的值 |
| --- | --- |
| manifest 大小 | 100 KiB |
| 名称长度 | 50 个字符 |
| entry 长度 | 200 个字符 |
| 导出项 | 100 |
| 声明式 imports | 50 |
| 描述性路由 | 100 |
| 请求 / grants | 每个列表 50 条声明 |

验证会检查下载的名称是否与注册名称一致。它检查自有属性，拒绝访问器和危险结构，并返回冻结的快照。不要在注册后使用 `manifest.wu.permissions.push(...)` 更改策略。

<span id="permisos-sintaxis-exacta"></span>

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

## 权限：准确语法

对象声明必须提供 `capability` 和**明确的 `resource`**。有效的字符串形式例如 `store.read:catalog`。需要同时声明 `required` 时使用对象；只需要能力与资源时使用字符串。

```js
// Solicitud de la aplicación:
const permission = {
  capability: 'store.read',
  resource: 'catalog',
  required: true,
};

// Dos formas equivalentes de conceder esa lectura desde el host:
const objectGrant = { capability: 'store.read', resource: 'catalog' };
const stringGrant = 'store.read:catalog';
```

对解析器而言，单独的 `store.read` 不是有效声明。TypeScript 输入声明允许一些更宽泛的值，因此即使编辑器没有要求，也必须明确补全资源。

`required` 默认为 `false`。被拒绝的可选权限会记录在诊断中，尝试对应操作时会被拒绝。设置 `required: true` 后，如果 shell 未覆盖整个请求，注册就会失败。

<span id="estrategia-de-carga-layout-y-estilos"></span>

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

## 加载策略、布局与样式

`strategy` 决定如何提前加载应用；参阅[加载与预加载](/zh-cn/docs/framework/loading/)，在挂载时加载、立即导入和提前获取资源之间做出选择。`fullBleed` 控制应用占满宿主高度还是随内容自然布局。两者均从应用配置中读取，但未列入 `WuAppConfig`。

在 manifest 中配置 `styleMode`。挂载将 `app.manifest.styleMode` 交给 sandbox；宿主顶层配置中的同名字段不会替代它。[sandbox 与 CSS 指南](/zh-cn/docs/framework/sandbox/)解释了如何组合私有和共享样式。

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

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

## 实现参考

实现：`src/core/wu-core.js`、`src/core/wu-core.js`、`src/core/wu-core.js`；解析器与限制：`src/core/wu-manifest.js`、`src/core/wu-manifest.js`、`src/core/wu-manifest.js`；策略：`src/core/wu-policy.js` 和 `src/core/wu-policy.js`。测试：`tests/unit/manifest-policy.test.js`、`tests/unit/manifest-dependencies.test.js`、`tests/unit/init-race.test.js`。