# v6.1.0 升级可行性评估（#11829）

> 评估时间：2026-06
> 关联：v6.1.0 Release Tracking #11813

本文档评估三个升级项的可行性与影响范围，每项给出明确结论与是否纳入本版本的建议。

---

## 1. Node.js 22 最低版本

### 现状

- `package.json` engines：`node: ">=20.0.0"`
- CI（`ci.yml` / `coverage.yml`）：仅运行 Node 20
- 本地开发环境：Node 22.22.0

### 调研

- **Node.js 20 (Iron) 已于 2026-03 进入 EOL**，不再接收安全更新，不应用于生产环境。
- **Node.js 22 (Jod) 是当前 Active LTS**，维护周期覆盖整个 v6.1.0 生命周期。
- 生态兼容性：`vitest` 已要求 `^18 || ^20 || >=22`（明确跳过 21），`@biomejs/biome` 要求 `>=14`，其余工具链对 Node 22 均无障碍。
- 升级成本低：Pro 自身代码不依赖 Node 20 特有行为，仅需调整 engines 与 CI 矩阵。

### 结论：✅ 建议本版本升级到 Node 22

理由：Node 20 已 EOL，继续以其为最低版本存在安全风险。Node 22 是当前 LTS 且生态完全就绪。

**落地动作（独立 PR）**：

- `package.json` engines 改为 `node: ">=22.0.0"`
- CI 工作流 `node-version` / `node_version` 矩阵改为 `22`
- 更新 `CLAUDE.md` 中 `Node ≥ 20` 的描述

---

## 2. utoopack（@utoo/pack）

### 现状

- `@utoo/pack` **不是项目直接依赖**，而是 `@umijs/max` 的传递依赖：
  ```
  @umijs/max → umi → @umijs/preset-umi → @umijs/bundler-utoopack → @utoo/pack@1.4.3
  ```
- 已安装版本 1.4.3，npm latest 为 1.4.9
- 项目仅在 `config/config.ts` 中通过 `utoopack: {}` 配置选项和 `require('@utoo/pack/package.json').version` 读取版本号

### 调研

- 由于 `@utoo/pack` 的版本由 `@umijs/max` 锁定，**不应在本项目中单独升级**——单独提升会与 Umi 的 bundler 版本产生不一致，且会在 `@umijs/max` 下次升级时被覆盖。
- 正确的升级路径是跟随 `@umijs/max` 升级（见 #11827），由 Umi 团队保证 bundler 与框架的兼容性。

### 结论：⏭️ 不单独升级，跟随 @umijs/max

理由：传递依赖应由上游框架管理。当前 1.4.3 随 `@umijs/max@4.6.x` 工作正常，构建验证通过。

---

## 3. @tanstack/react-query v6

### 现状

- 当前版本：5.100.x（#11828 已升至 5.100.14）
- 通过 `@umijs/max` 的 reactQuery 插件集成（`config/config.ts` 中 `reactQuery: {}`）

### 调研

- npm dist-tags 显示 **react-query 尚无 v6 发布**：
  ```
  latest: 5.100.14   （无 v6 / next-major tag）
  ```
- v5 仍在活跃维护，持续发布小版本。

### 结论：⏭️ v6 未发布，继续跟随 v5 最新版

理由：v6 不存在，无迁移路径可言。保持 v5 最新（5.100.14）即可。待 v6 发布后再单独评估迁移成本（届时需关注 Umi reactQuery 插件的适配）。

---

## 汇总

| 评估项 | 结论 | 是否本版本执行 |
|--------|------|----------------|
| Node.js 22 最低版本 | ✅ 建议升级（Node 20 已 EOL） | 是，独立 PR |
| utoopack | ⏭️ 跟随 @umijs/max，不单独升级 | 否 |
| @tanstack/react-query v6 | ⏭️ v6 未发布，跟随 v5 | 否 |