# Claude Code批量迁移五大战役全流程 ## 概述 代码迁移是每个技术团队迟早要面对的硬仗——Vue 2终止维护、React Class组件淘汰、JavaScript向TypeScript全面转型、REST API迁移到GraphQL、CSS重构到Tailwind。传统迁移依赖人工逐文件修改，动辄数周甚至数月。Claude Code凭借1M token上下文窗口、`/batch`并行分解、worktree隔离执行、自定义Skill四大核心能力，将迁移周期从数周压缩到数天。本教程面向有Claude Code基础使用经验的中高级开发者，系统讲解五类最常见的代码迁移场景如何用Claude Code高效完成。 ## 前置条件 - Claude Code CLI ≥ v2.1.63（支持`/batch`命令） - Git ≥ 2.30（支持worktree） - 目标项目已纳入Git版本控制 - 基本了解CLAUDE.md配置方法 - 建议使用Claude Opus 4.6模型（1M上下文窗口，迁移效果最佳） ## 迁移架构总览 ```text graph TD A[迁移需求分析] --> B{迁移类型判断} B --> C1[战役一: 语言迁移
JS → TypeScript] B --> C2[战役二: 框架升级
Vue2 → Vue3] B --> C3[战役三: 组件迁移
Class → Hooks] B --> C4[战役四: API迁移
REST → GraphQL] B --> C5[战役五: 样式迁移
CSS → Tailwind] C1 & C2 & C3 & C4 & C5 --> D[CLAUDE.md迁移配置] D --> E{规模评估} E -->|<50文件| F[单Agent直接迁移] E -->|50-200文件| G[/batch并行分解] E -->|>200文件| H[分阶段+worktree隔离] F & G & H --> I[自动化测试验证] I --> J[人工Review + 合并] ``` ## 迁移前准备：构建迁移CLAUDE.md 所有五大战役共享一个核心前提——在项目根目录创建专门的迁移配置。这不是简单的"告诉Claude你要迁移"，而是一份结构化的迁移蓝图。 ```markdown # CLAUDE.md — 迁移专用配置 ## 项目概况 - 项目名称: my-enterprise-app - 技术栈: Vue 2.6 + Vuex + JavaScript + SCSS - 文件总数: 约850个源文件 - 测试覆盖率: 42% ## 当前迁移阶段 - [x] Phase 1: JavaScript → TypeScript（已完成60%） - [ ] Phase 2: Vue 2 → Vue 3 Composition API - [ ] Phase 3: SCSS → Tailwind CSS - [ ] Phase 4: Vuex → Pinia ## 迁移规则 1. 每次迁移只处理一个模块，不要跨模块修改 2. 迁移后必须保持现有测试通过 3. 优先迁移工具函数和类型定义，最后迁移UI组件 4. 不允许在迁移过程中引入新功能 5. 每个文件迁移后必须能独立编译 ## 禁止操作 - 不要删除任何现有测试 - 不要修改构建配置（webpack/vite）除非迁移要求 - 不要在迁移PR中混合非迁移改动 ## 文件路径约定 - 类型定义: src/types/ - 工具函数: src/utils/ - 组件: src/components/ - 页面: src/views/ - 状态管理: src/store/ ``` **关键原则**：CLAUDE.md中的迁移规则越精确，Claude Code产生幻觉或越界修改的概率越低。上述配置将"不要做什么"和"按什么顺序做"都写得清清楚楚。 --- ## 战役一：JavaScript → TypeScript 全面转型 ### 1.1 场景分析 这是最基础的迁移战役，也是后续所有战役的地基。一个中型项目通常有数百个`.js`文件需要转为`.ts`，涉及JSDoc类型标注转换、隐式any处理、第三方库类型声明安装等。 ### 1.2 分阶段执行策略 **阶段一：生成类型基础** ```bash # 第一步：让Claude Code分析项目并生成类型蓝图 claude -p "分析整个src/目录下的JavaScript文件，列出： 1. 所有导出的函数签名及其参数/返回类型 2. 所有接口和类型别名（从JSDoc中提取） 3. 第三方依赖中缺少@types/声明的包 4. 建议的迁移优先级排序 输出为markdown表格格式。" --output-format text > migration-type-audit.md ``` 这一步利用Claude Code的`-p`模式（非交互式打印模式）进行全项目扫描，输出结构化的类型审计报告。`--output-format text`确保输出纯文本，方便后续处理。 **阶段二：批量安装类型声明** ```bash # 基于审计报告，批量安装缺失的类型声明 claude -p "读取 migration-type-audit.md，生成npm命令来安装所有缺失的@types/包。 只输出可以直接执行的命令，不要任何解释。" --allowedTools "Bash(read_only)" ``` 注意`--allowedTools`限制了Claude只能使用只读Bash命令，防止在规划阶段意外修改文件。 **阶段三：逐模块迁移** ```bash # 对单个模块进行类型迁移 claude "将 src/utils/ 目录下所有 .js 文件迁移为 .ts： 1. 添加完整的类型注解，不使用any 2. 将JSDoc @param/@returns 转为TypeScript类型语法 3. 确保tsconfig strict模式编译通过 4. 保留所有现有导出签名不变 5. 运行 tsc --noEmit 验证" ``` **阶段四：大规模并行迁移（/batch模式）** 当迁移超过50个文件时，手动逐模块操作效率太低。`/batch`命令是专为这种场景设计的： ```bash # 在Claude Code交互会话中执行 /batch 将 src/components/ 下所有 .js 文件迁移为 .tsx，遵循以下规则： - 添加Props接口类型定义 - 将所有React.PropTypes转换为TypeScript类型 - 确保每个组件文件独立可编译 - 不修改组件逻辑或UI表现 ``` `/batch`内部执行流程： 1. Claude分析目标范围，将变更分解为5-30个独立单元 2. 每个单元分配一个后台Agent 3. 每个Agent在独立的git worktree中执行 4. 所有Agent完成后，汇总结果并创建PR ```mermaid sequenceDiagram participant U as 开发者 participant C as Claude Code participant P as 规划Agent participant W1 as Worktree Agent 1 participant W2 as Worktree Agent 2 participant W3 as Worktree Agent 3 U->>C: /batch JS→TS迁移 src/components/ C->>P: 分析并分解迁移单元 P->>C: 返回15个独立迁移单元 C->>W1: Agent 1: Button, Modal, Tooltip C->>W2: Agent 2: Table, Form, Input C->>W3: Agent 3: Card, Tab, Dropdown Note over W1,W3: 并行在独立worktree中执行 W1-->>C: 迁移完成 + diff W2-->>C: 迁移完成 + diff W3-->>C: 迁移完成 + diff C->>U: 汇总15个文件迁移结果 ``` ### 1.3 常见问题与解决 | 问题 | 原因 | 解决方案 | |------|------|----------| | 迁移后类型报错过多 | 第三方库缺少类型 | 在CLAUDE.md中添加`// @ts-ignore`过渡策略 | | `/batch`部分Agent失败 | 组件间存在隐式依赖 | 先迁移独立组件，依赖密集的组件单独处理 | | 迁移改变了函数签名 | Claude过度推断类型 | 在CLAUDE.md中明确"保持现有导出签名不变" | --- ## 战役二：Vue 2 → Vue 3 框架升级 ### 2.1 场景分析 Vue 2已于2023年12月停止维护。大量企业项目仍停留在Vue 2，面临Options API到Composition API的迁移、Vuex到Pinia的状态管理迁移、过滤器（filters）废弃等破坏性变更。 ### 2.2 迁移前审计 ```bash # 使用-p模式生成迁移审计报告 claude -p "扫描整个项目，生成Vue 2到Vue 3迁移审计报告： 1. 使用了哪些Vue 2专有API（$set, $delete, $on, $off, filters等） 2. 依赖的Vue 2专有库（vue-router v3, vuex v3等） 3. 使用了v-model的组件（Vue 3语法变更） 4. 使用了$children的组件（已移除） 5. 使用了$listeners的组件（已合并到$attrs） 6. 每个组件的迁移复杂度评估（简单/中等/复杂） 输出JSON格式。" --output-format json > vue-migration-audit.json ``` ### 2.3 分层迁移策略 **第一层：构建配置升级** ```bash claude "升级构建配置以支持Vue 3： 1. webpack.config.js中替换vue-loader配置 2. 更新alias: 'vue$' → 'vue/dist/vue.esm-bundler.js' 3. 安装 @vue/compiler-sfc 替代 vue-template-compiler 4. 配置兼容模式 @vue/compat（渐进迁移策略） 5. 运行 webpack --mode development 验证构建通过" ``` **第二层：兼容模式启动** 使用`@vue/compat`实现渐进迁移——它允许Vue 2和Vue 3代码共存： ```bash claude "配置Vue兼容模式： 1. 安装 @vue/compat 2. 修改 main.js 入口使用兼容构建 3. 配置全局兼容配置，对已迁移组件禁用兼容警告 4. 创建迁移进度追踪文件，记录哪些组件已完成迁移 5. 启动dev server验证应用正常运行" ``` **第三层：逐组件迁移（/batch并行）** ```bash # 对简单组件批量迁移 /batch 将 src/components/common/ 目录下的Vue 2组件迁移为Vue 3 Composition API： - Options API →