# 各应用的依赖与版本

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

<span id="instalar-desde-declaraciones-de-cada-parte"></span>

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

## 根据各部分的声明安装

```bash
wu install
```

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

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

<span id="resolución-de-bibliotecas"></span>

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

## 库的版本解析

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

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

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

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

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

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

<span id="identidad-de-módulos-en-desarrollo"></span>

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

## 开发中的模块身份

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

<span id="toolchains-distintas"></span>

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

## 不同工具链

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

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

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

<span id="dependencias-locales"></span>

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

## 本地依赖

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

<span id="reescritura-del-manifiesto-raíz"></span>

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

## 重写根清单

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

```bash
wu install --force
```

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

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

<span id="migrar-un-proyecto-a-cli-12"></span>

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

## 迁移项目到 CLI 1.2

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

```sh
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` 维护。

<span id="salidas-y-errores"></span>

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

## 输出与错误

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

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

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

## 实现参考

- `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`