taiga-ui-migration

目标

成功将 Taiga UI 项目迁移到下一个主版本，同时：

• 保留运行时行为、模板输出、样式和构建工具
• 安全、系统地处理原理图执行后的 TODO
• 识别并解决常见迁移问题
• 通过仔细验证，将破坏性变更降至最低

步骤 0：执行操作前收集上下文

重要： 在执行任何命令或编辑任何文件之前，收集并确认以下信息：

问题	查看位置
源版本和目标主版本	如果用户未说明，请询问用户
包管理器（npm / yarn / pnpm）	package.json → packageManager 字段或锁文件是否存在
构建系统（Angular CLI / Nx）	是否存在 nx.json 或 angular.json
Monorepo：受影响的应用/库数量	nx.json → projects，或 angular.json → projects
自定义 webpack / ESBuild 配置	angular.json → builder 字段

如果 Taiga UI MCP 服务可用， 现在使用 get_migration_guide 加载 {CURRENT_MAJOR} → {NEXT_MAJOR} 迁移说明，再继续操作。这将为整个会话提供权威的破坏性变更信息。

只有表格中的所有项目都已确认，才能继续进入阶段 1。

开始前 - 先决条件检查清单

• Node.js：使用 Node.js LTS 版本
• NPM：版本 10 或更高（或使用 yarn/pnpm 时的等效版本）
• 当前 Taiga UI：先更新到 v{CURRENT_MAJOR} 的最新版本
• Angular：更新到与 v{NEXT_MAJOR} 兼容的版本（查看迁移指南）
• Prettier：将 endOfLine 选项设为 auto，以防止迁移后出现换行符问题

⛔ 切勿使用 --legacy-peer-deps、--force 或任何绕过依赖解析的标志。 这些标志会掩盖真实的版本冲突，导致运行时故障。请改为明确解决冲突。

迁移工作流

阶段 1：运行迁移原理图

对于 Angular CLI 项目：

ng update @taiga-ui/cdk

对于 Nx 项目：

nx migrate @taiga-ui/cdk
nx migrate --run-migrations=migrations.json

阶段 2：检查更改的代码

原理图执行完成后：

1. 检查所有更改的代码行 - 有些更改会添加新的代码注释（例如 // TODO: (Taiga UI migration)）。这些注释通常包含手动迁移已删除实体并使用新替代方案的说明。

2. 检查 @taiga-ui/legacy 导入 - 你可能会发现从 @taiga-ui/legacy 导入的新内容。这是一个过渡包，用于在过时实体被完全移除之前提供支持：

   • 此包中的所有内容都会在 v{NEXT_MAJOR+1} 中移除
   • 你可以暂时继续使用它们
   • 大多数已弃用实体都有现代替代方案，并标有 @deprecated 标签（IDE 会以删除线显示这些内容）
   • 强烈建议：尽快替换为现代替代方案

阶段 3：处理迁移 TODO

处理原理图执行后的 TODO，同时不破坏运行时行为、模板输出、样式或构建工具。

TODO 的核心规则

• TODO 不代表可以猜测，而是提示你验证哪些更改确实安全。
• 处理范围内所有可执行的 TODO，但只有在依据附近代码和使用情况证明每项修复可行后，才能进行修复。
• 优先采用能保留当前行为的最小改动。
• 除非代码库能证明某个已弃用包、导入或实用工具未被使用，否则切勿仅因 TODO 提示就将其移除。
• 如果某项修复可能改变逻辑、生成的标记、CSS 应用方式或脚本行为，请先验证相关用法。
• 如果无法确定安全的修复方式，请询问用户，不要自行编造代码。

TODO 处理顺序

从共享模块和 barrel 文件（index.ts、public-api.ts）开始处理 TODO，以解除使用方的阻塞，然后依次处理服务、组件，最后处理样式入口。完成一个文件中的所有 TODO 后，再处理下一个文件。如果无法完成某个文件，请在 MIGRATION_ISSUES.md 中添加一条 Quick Entry，然后继续。

TODO 分类 → 必须使用的问题模板

类别	停止条件	要询问的问题
模板/DI（高优先级）	存在直接替换方案	通常可以安全修复，无需询问
移除样式包	在模板中发现该包中的任意类	“我发现 <className> 在 <file> 中使用。迁移完成前，是否应保留旧样式包？”
没有直接替换方案	TODO 明确说明了这一点	“迁移说明指出 <API> 已移除，且没有直接替换方案。应使用什么行为来替代它？”
动态绑定	[input]="expr" 中的 expr 是运行时值	“绑定 [appearance]="mode" 使用了运行时值。新 API 是否应接受相同的值？”
存在多种有效方案	文档中存在多个替换方案	“有两种替换方案：<A> 和 <B>。哪一种符合你的预期行为？”
仅警告	TODO 表示需要手动决定	“这个 TODO 需要你做出决定：<TODO text>。你倾向于采用哪种方案？”

分类示例：

• TODO: replace TuiButtonModule with TuiButton → 模板/DI（高优先级，通常安全）
• TODO: remove @taiga-ui/styles import → 样式包（停止，先检查用法）
• TODO: migrate to standalone component API → TypeScript（中优先级，检查使用方）
• TODO: this API was removed, no direct replacement → 仅警告（询问用户）

TODO 工作流

1. 识别并分类 TODO，使用上表
2. 使用 MCP 查找替换方案（如可用）：
   • 对于组件替换：使用新组件名称调用 get_component_example
   • 对于架构变更：调用 get_overview 或 migration_guide
   • 仅当仅凭本地代码上下文即可明确替换方案时，才跳过此步骤
3. 编辑前追踪实际用法：
   • 搜索当前组件、模板、样式和附近文件中的直接引用
   • 对于样式相关的 TODO，遵循下方的样式包移除算法
   • 确认 TODO 针对的是单个位置还是更广泛的模式
4. 判断 TODO 是否可以安全执行：
   • 如果存在一对一替换方案且能保留原有行为，则应用该方案
   • 如果提到了已弃用的包，在删除前检查运行时、模板或样式是否仍依赖它
   • 如果存在多种可能的替换方案，或修复依赖动态绑定或生成的输出，则停止并使用问题模板询问用户
5. 应用最小的安全修复：
   • 将更改限制在相关范围内
   • 除非为保留行为所必需，否则避免大范围重构
   • 除非周边证据支持移除，否则不要删除导入、包或脚本
6. 验证结果：
   • 重新检查修改区域，确保逻辑、类和选择器仍然匹配
   • 尽可能对受影响部分运行范围最小的检查
   • 如果验证后仍觉得存在歧义，不要扩大补丁；应询问用户

阶段 4：故障排查

问题：TypeScript 错误 TS6133——声明了变量，但从未读取其值

**解决方案：**迁移原理图有意不包含代码格式化功能（这会拖慢执行速度）。请使用 IDE 或代码检查工具：

• WebStorm：右键单击根文件夹 →“优化导入”（递归移除所有未使用的导入）
• Visual Studio Code：对所有文件递归使用“整理导入”文件夹源操作
• ESLint/Prettier：运行经过优化的规则，清理未使用的导入

问题：Yarn 用户需要兼容旧版 peer dependencies 的变通方案

**解决方案：**Taiga UI 依赖许多 Taiga Family 软件包。Yarn 和 pnpm 不会自动安装传递性 peer dependencies。请手动检查每个 Taiga UI 软件包的 package.json，并安装缺失的 peer dependencies。

问题：无法解析 ng-web-apis、maskito、ng-polymorpheus 或 ng-event-plugins 的依赖项

**解决方案：**同上——手动检查每个 Taiga UI 软件包的 package.json，并安装传递性 peer dependencies

问题：运行 nx migrate --run-migrations 后出现 Cannot find module 'ts-morph' 错误

**解决方案：**这是 Nx 的 ng migrate 命令问题。可以：

• 升级 Nx 版本，或
• 运行 npm install，然后重新运行迁移

问题：FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

**解决方案：**迁移原理图会递归遍历每个文件和目录，因此可能占用大量内存。请提高 Node.js 进程的内存限制：

NODE_OPTIONS="--max-old-space-size=4096" ng update @taiga-ui/cdk

问题：基本的 ng update / nx migrate 命令失败，需要手动执行原理图

解决方案：

1. 在 package.json 中手动将所有 Taiga UI 软件包更新至 v{NEXT_MAJOR}（不要使用控制台命令更改版本，然后运行 npm install）
2. 确认 node_modules/@taiga-ui/cdk/package.json 中包含 v{NEXT_MAJOR} 版本
3. 执行：

Angular CLI：

ng update @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version> --to=@taiga-ui/cdk@<new-version>

Nx：

nx migrate @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version>
nx migrate --run-migrations=migrations.json

记录不确定或有问题的迁移点

遇到无法立即解决的迁移问题时，请创建并维护一个专用文件（例如 MIGRATION_ISSUES.md 或 TODO_MIGRATION.md），用于跟踪所有不确定或可能有问题的部分。

双层文档格式

快速条目（适用于简单明确的阻塞问题）：

- [ ] `src/app/button.component.html:34` — `TuiButtonModule` TODO,
      blocked: dynamic `[appearance]` binding, need user input

以下情况使用快速条目：

• 涉及单个文件，且阻塞原因明确的问题
• 从 TODO 中即可看出应询问什么的情况
• 需要用户决定的轻微样式软件包用法问题

完整条目（仅适用于影响多个文件或可能改变行为的情况）：

以下情况使用下面的 7 字段格式：

• 涉及多个文件的问题
• 可能导致行为变化的问题
• 复杂的样式软件包依赖项
• 需要详细说明的情况

完整条目的必需格式

每个记录的问题都必须包含：

1. 文件路径——受影响文件的完整相对路径（或文件列表）
2. 行号——问题发生的确切行号
3. 原始代码——尝试修复前的代码片段
4. 问题描述——清楚说明不确定或有问题之处
5. 尝试过的解决方案——你考虑过哪些迁移方案，以及它们可能无效的原因
6. 潜在影响——如果应用了错误的修复，可能会导致什么问题（运行时、模板、样式、构建）
7. 迁移版本——相关的 Taiga UI 版本迁移（如果已知）

完整条目格式示例

## Issue #<number>: <Brief description>

**Files:**

- `path/to/component.ts`
- `path/to/component.html`

**Lines:** 42, 15

**Migration:** v4 -> v5

**Original code:**

```typescript
// TODO: migrate to new button API
@Input() mode: 'accent' | 'primary' = 'primary';
```

```html
<button [mode]="mode">Click me</button>
```

**Issue:**
The old `mode` input was replaced with a new directive-based API, but this component
uses dynamic binding that may not be compatible with the new approach.

**Attempted solutions:**

- Direct replacement with `tuiAppearance` - unclear if dynamic values work
- Keeping old API temporarily - requires deprecated module import

**Potential impact:**

- Runtime error if binding fails
- Visual regression if styling is not applied correctly

工作流集成

1. **初始扫描期间：**在迁移会话开始时创建迁移问题文件
2. **遇到阻塞时：**先添加一个快速条目，再继续处理下一个 TODO
3. **询问用户之前：**在问题中引用已记录的条目
4. **问题解决后：**将条目标记为已解决，并简要注明采用的修复方案

完成标准

满足以下所有条件时，迁移会话即告完成：

• 源文件中不再有 // TODO: (Taiga UI migration) 注释，或每个剩余的 TODO 都在 MIGRATION_ISSUES.md 中有对应条目
• 不再导入 @taiga-ui/legacy，或每个剩余的导入都已获得用户明确认可
• ng build / nx build 执行完成且没有错误
• 没有引入新的 TypeScript 错误（TS6133 未使用导入错误可以接受——按照阶段 4 中的说明通过 IDE 解决）
• MIGRATION_ISSUES.md 中的所有条目都已展示给用户

除了迁移所需的操作外，不要重构、重命名或改进代码。

何时询问用户

所有与 TODO 相关的决策都使用 TODO 分类表中的问题模板。

此外，遇到以下情况时也应询问：

• 迁移 schematic 执行失败或产生意外错误
• 项目有可能影响迁移的自定义配置
• 无法自动确定步骤 0 中的上下文
• 无法通过对齐 Taiga UI 软件包版本来解决 peer dependency 冲突

不要做什么

• 不要使用 --legacy-peer-deps、--force 或任何绕过依赖解析的标志；如果 .npmrc 中原本没有 legacy-peer-deps=true，也不要添加它——这些操作会掩盖真实的版本冲突，导致迁移在运行时失败；应明确解决冲突
• 不要仅根据 TODO 文本硬编码修复方案
• 不要先删除已弃用的依赖，再事后发现问题
• 不要为处理迁移 TODO 而改写无关代码
• 如果已知实际修复方法且安全，不要用新的警告来压下 TODO
• 如果无法根据本地代码上下文解释更改为何安全，就不要继续
• 不要跳过先决条件检查清单——确保环境已做好准备
• 不要跳过步骤 0（收集上下文）——行动前先了解环境