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

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

变更概览

• **Framework：**hook 使用应用身份和权限；SSR 支持每请求私有数据、取消和并发限制；嵌套路径同步；监督和协作式重放。参见运行时可靠性和适配器。

• **安全：**明确的远程来源、MCP 中继双向认证、契约所有权、.wuapp 验证、AI 工作流权限以及每响应 CSP nonce。参见安全。

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

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

1. 准备可回退的升级

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

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，并使用其包管理器安装。

2. 处理不兼容变更

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

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 拒绝远程应用。参见远程应用。

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

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

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

3. 验证与必要时回退

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

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

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

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