使用 CLI6 分钟阅读 · MARKDOWN ↗

各应用的依赖与版本

wu install 汇总哪些内容、如何解决主版本差异，以及何时创建本地工具链。

根据各部分的声明安装

wu install

wu i 是别名。该命令汇总 shell 和应用的依赖声明，编辑根清单并调用 npm。若没有声明 wu-framework 或 esbuild，则使用目录中的版本添加它们。wu add 和 wu create 向导使用同一安装器。

在需要依赖的微应用或消费它的 shell 中添加依赖，再运行 wu install。仅在根目录运行 npm install 不会重新计算汇总清单或 .wu-deps.json。

库的版本解析

兼容范围取交集：^19.0.0 与 ^19.3.0 得到 ^19.3.0。不兼容的组使用别名，最新组保留主名称。解析器区分 0.x 系列（zone.js--0.15）及同一主版本中不兼容的固定版本（lodash--4.17.20）。每个包只出现在根清单的一个区段中；任一应用在 dependencies 中声明它时，该区段优先。

{
  "dependencies": {
    "react": "^19.0.0",
    "react--17": "npm:react@^17.0.0"
  }
}

overrides 映射把每个原始 import 关联到正确的别名：

{
  "mf-legacy": {
    "react": "react--17"
  }
}

键使用 mf-legacy 这样的目录，而不是 legacy 这样的目录条目名称。开发和构建都会加载该映射。这不代表所有 React 使用者共享一个实例：每组兼容的消费者都必须解析到正确的身份。

解析支持 ^、~、比较符、精确版本、通配符、部分版本、连字符范围及最多 32 个 || 分支。它不应用 npm 将预发布版本限定到比较符相同版本三元组的附加规则，因此使用预发布版本时应检查安装结果。dist-tag、Git URL 等非 SemVer 值保留为显式固定值，不同声明会产生警告。

开发中的模块身份

每个 import 从写入它的源文件解析，遵循本地和嵌套的 node_modules、pnpm、链接及 .wu-deps.json。URL 标识版本和位置。shared 中的包，以及始终共享的 wu-framework，从根目录解析为单一实例；不兼容的本地副本会产生警告。需要多个版本共存的库不应放入 shared。

不同工具链

Vite、插件和其他编译工具需要不同策略。算法在仍共享根目录的应用中选择声明数量最多的主版本，平票时选择较大版本。不兼容的应用改用本地安装。这个决定会重复计算，因为移除某应用的投票可能改变另一项多数结果。

{
  "mf-vite-antiguo": {
    "_toolchain": "local"
  }
}

CLI 在该应用内安装依赖，构建使用其 node_modules/vite。每次安装都会重写映射，不再有 overrides 时则删除它。WU 管理的本地依赖树带有来源信息，以便不再需要时移除。

本地依赖

file: 声明会保留，并改写为相对于根目录的路径。例如，mf-panel/package.json 中的 file:../ui 会在汇总清单中转换为指向 ui/ 的路径。当前收集器跳过 link: 和 workspace: 声明；此机制不是完整的 npm workspace 管理器。

重写根清单

不含 _wu 的根清单会被拒绝，退出码为 1。--force 允许管理该文件并保留其字段和依赖；若 JSON 已损坏，则替换它，并将原文件保存在 package.json.bak。

wu install --force

--force 或 -f 属于 WU：它们允许重写，并非通用 npm 参数透传。没有公开的 --frozen-lockfile、--offline、--no-install 或包管理器选择选项。

_wu.managed 记录 WU 写入的依赖，以便只移除已无应用声明的条目。自定义脚本、workspaces、overrides、engines 和手动添加的依赖都会保留。仅在缺失时创建 dev 和 build。JSON 采用原子写入并保留 .bak 副本；旧 _wu 标记在首次安装时迁移。

迁移项目到 CLI 1.2

wu update 更新全局工具。wu upgrade 将 shell 和应用与已安装 CLI 的目录比较，1.2.0 的目标为 WU Framework ^4.0.0。请先查看框架迁移：更新版本范围不会自动迁移所有 API。

wu upgrade --dry-run
wu upgrade --json
wu upgrade --yes
wu install
wu doctor --json
wu build

不带参数时，upgrade 显示计划并请求确认。--dry-run 不写入；--json 仅与 --yes 配合时应用；有待处理更改时 --check 返回 2。它不会降级：保留更新的范围、开放范围和非 SemVer 协议。精确固定版本需要 --force，但仍不允许降级。缺失依赖只报告，不自动添加。发生错误或需要确认却没有终端时返回 1。

迁移识别旧模板并保存 <file>.bak：独立的 Stencil 标签、移除未使用的 @stencil/core、使用 DOM API 的 Astro shell、带 CSS.escape 的选择器、缺失的 .gitignore 规则以及 shared 中的 Qwik/Svelte 运行时。更改具有幂等性；不匹配的自定义源码会保持不变并提示。该命令不安装依赖，最后需执行 wu install。

版本范围示例：声明的 wu-framework: ^3.2.1 变为 ^4.0.0；react: ^19.4.0 高于目录中的 ^19.3.0，因此保留；react: 19.2.0 保留固定版本，除非使用 --force。不要手动添加 _wu.managed，该字段由 wu install 维护。

输出与错误

配置或应用清单中的无效 JSON 会在写入前终止安装，并报告行号、列号和退出码 1。写入失败、未带 --force 的非 WU 根清单以及根目录或本地工具链的 npm 失败也返回 1。库冲突时，根目录调用包含 --legacy-peer-deps。

实现参考

wu-cli/src/commands/install.zig
wu-cli/src/commands/upgrade.zig
wu-cli/src/commands/codemods.zig
wu-cli/src/config/semver.zig
wu-cli/src/config/json_doc.zig
wu-cli/src/runtime/module_graph.zig
wu-cli/tests/install-preserva.test.cjs
wu-cli/tests/upgrade.test.cjs
wu-cli/tests/dev-module-resolution.test.cjs