# WU Framework 4.0 与 CLI 1.2：升级和迁移

迁移到 Framework 4.0.0 和 CLI 1.2.0 的新功能、不兼容变更、验证和支持。

本指南适用于 WU Framework **4.0.0** 和 WU CLI **1.2.0**。Framework 4 是一个主版本，因为它现在会拒绝旧版本曾接受的操作。更新 CLI 不会自动迁移你的应用代码。

<span id="qué-cambia"></span>

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

## 变更概览

- **Framework：**hook 使用应用身份和权限；SSR 支持每请求私有数据、取消和并发限制；嵌套路径同步；监督和协作式重放。参见[运行时可靠性](/zh-cn/docs/framework/runtime-reliability/)和[适配器](/zh-cn/docs/framework/api-adapters/)。

- **安全：**明确的远程来源、MCP 中继双向认证、契约所有权、`.wuapp` 验证、AI 工作流权限以及每响应 CSP nonce。参见[安全](/zh-cn/docs/framework/security/)。

- **CLI：**依赖和目录、按应用解析、并行编译及配置感知缓存失效；开发服务器仅允许授权主机；使用内容哈希和一致的资源部署。参见[依赖](/zh-cn/docs/cli/dependencies/)、[开发](/zh-cn/docs/cli/development/)和[构建](/zh-cn/docs/cli/build/)。

CLI 1.2 使 `WU_D003` 与目录中的 Framework 版本保持一致。诊断会区分不兼容的依赖和有效的 Framework 4 项目。它还修复了 Windows 上包含带引号路径的构建命令的执行问题。

<span id="1-preparar-una-actualización-reversible"></span>

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

## 1. 准备可回退的升级

将代码、清单和锁文件提交到版本库，并保留上一个生产构建产物。先在分支和测试环境中升级。安装精确版本并确认正在使用的可执行文件。

```sh
npm view wu-framework@4.0.0 version
npm view @wu-framework/cli@1.2.0 version
npm install --global @wu-framework/cli@1.2.0 --include=optional
wu --version
```

在现有工作区中，查看 `wu upgrade --help`，运行 `wu upgrade` 并检查差异。工具更新依赖和集成文件，但不会重写 grants、hooks 或业务契约。随后运行 `wu install`。不使用 CLI 的项目应将相关包中的 `wu-framework` 更新为 `4.0.0`，并使用其包管理器安装。

<span id="2-corregir-los-cambios-incompatibles"></span>

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

## 2. 处理不兼容变更

**Hooks 和 store。**微应用内的 hook 不再继承宿主权限。在 `manifest.wu.permissions` 中申请权限，在 shell 的 `grants` 中授予权限，只有交集生效。被拒绝的 emit 返回 `false`；订阅或 store 访问可能抛出 `WU_EVENT_SUBSCRIBE_DENIED` 或 `WU_CAPABILITY_DENIED`。只授予应用实际使用的通道和路径。

```js
const permissions = [
  "store.read:cart.*", "store.write:cart.*",
  "events.emit:cart:changed", "events.subscribe:cart:changed",
];
await wu.registerApp({
  name: "cart", url: "/apps/cart/", sandbox: "module",
  manifest: { name: "cart", entry: "index.js", wu: { permissions } },
  grants: permissions,
});
```

**远程应用。**`connect` 和 `waitForPort` 必须提供 `hostOrigin`。请使用 shell 的精确来源；`"*"` 表示主动接受任意来源。入口来源必须与注册 URL 一致，否则出现 `WU_REMOTE_ORIGIN_MISMATCH`。同源远程应用需要 `iframe.allowSameOrigin: true`；`wu.detach()` 会以 `WU_WINDOW_REMOTE_UNSUPPORTED` 拒绝远程应用。参见[远程应用](/zh-cn/docs/framework/remote-apps/)。

**MCP 和 CSP。**中继必须与运行时一起升级：4.0 bridge 使用 HMAC v2 双向认证并要求令牌。环回地址之外禁止明文 `ws://`。不安全模式只能显式用于本地。在 SSR 中间件中，将固定 nonce 改为 `nonce: () => createNonce()`，为每次响应生成新值。参见[MCP](/zh-cn/docs/framework/api-mcp/)和[流式渲染与安全](/zh-cn/docs/framework/streaming-security/)。

**契约和包。**不要覆盖其他提供者的 capability（`WU_CAPABILITY_OWNED`）；交接前先撤销或卸载提供者。在宿主已注册的应用上安装 `.wuapp` 需要 `{ replace: true }`。`restore()` 验证已存储条目。应通过 `error.code` 而非消息文本处理错误，并使用 `await` 等待异步生命周期。

**CLI 和部署。**将隧道主机添加到 `dev.allowedHosts`；`.env` 中只有 `VITE_*` 和 `WU_*` 键会暴露给客户端。这些前缀不适合存放秘密。多个应用需要单一实例时检查 `shared`。部署完整的 `dist/`；旧页面仍打开时保留旧的哈希资源，并重新验证 HTML/清单。参见[配置](/zh-cn/docs/cli/configuration/)和[部署](/zh-cn/docs/cli/serve/)。

<span id="3-validar-y-volver-atrás-si-es-necesario"></span>

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

## 3. 验证与必要时回退

```sh
wu doctor --json
wu contracts check
wu test
wu build
wu serve 4100 --mode static
```

按实际使用的功能验证挂载、更新、卸载、权限拒绝、直接刷新、SSR/水合、CSP、RPC 和远程重连。如使用 `wu build --native`，还应单独测试。也要检查部署前已打开的标签页。发生故障时，同时恢复之前的提交、锁文件和构建产物；不要混用新运行时与不兼容的中继或资源。

<span id="se-rompió-algo-te-ayudamos"></span>

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

## 遇到问题？我们可以提供帮助

WU 团队会帮助诊断升级问题。[请求迁移支持](/zh-cn/support/#migration-help)，或在产品仓库创建 issue。请附上新旧版本、`wu --version`、`npm ls wu-framework`、系统/浏览器、错误码及不含秘密的最小复现，说明升级前正常的行为和预期结果。社区支持不承诺固定响应时限。