# 迁移命令使用

<cite>
**本文引用的文件**
- [vendor/xia/migration/src/command/migrate/Create.php](file://vendor/xia/migration/src/command/migrate/Create.php)
- [vendor/xia/migration/src/command/migrate/Run.php](file://vendor/xia/migration/src/command/migrate/Run.php)
- [vendor/xia/migration/src/command/migrate/Rollback.php](file://vendor/xia/migration/src/command/migrate/Rollback.php)
- [vendor/xia/migration/src/command/migrate/Status.php](file://vendor/xia/migration/src/command/migrate/Status.php)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php](file://vendor/xia/migration/src/command/migrate/Breakpoint.php)
- [vendor/xia/migration/src/command/Migrate.php](file://vendor/xia/migration/src/command/Migrate.php)
- [vendor/xia/migration/src/Creator.php](file://vendor/xia/migration/src/Creator.php)
- [vendor/xia/migration/src/Migrate.php](file://vendor/xia/migration/src/Migrate.php)
- [vendor/xia/migration/src/Service.php](file://vendor/xia/migration/src/Service.php)
- [AGENTS.MD](file://AGENTS.MD)
- [composer.json](file://composer.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 ThinkCMF 使用者，系统化讲解 xia/migration 包提供的数据库迁移命令，覆盖迁移创建、执行、回滚、状态查看与断点管理等常用能力，并结合 ThinkCMF 的应用与插件迁移目录组织方式，给出最佳实践、常见组合与排障建议。

## 项目结构
- ThinkCMF 通过 Composer 引入 xia/migration 包，该包基于 Phinx 实现迁移能力，并在 ThinkPHP 控制台框架下注册命令。
- 迁移命令由 ThinkPHP Console 提供，具体实现位于 vendor/xia/migration/src/command 下，核心逻辑封装在 vendor/xia/migration/src/Migrate.php 中。
- 迁移文件默认存放路径为：
  - ThinkCMF 核心：vendor/thinkcmf/cmf/src/data/migrations
  - 应用（App）：{app}/data/migrations
  - 插件（Plugin）：plugins/{plugin}/data/migrations
- 迁移记录表默认命名规则：
  - ThinkCMF 核心：migration
  - 应用：{app}_migration
  - 插件：plugin_{plugin}_migration

```mermaid
graph TB
A["ThinkCMF 应用"] --> B["Console 命令入口"]
B --> C["Migrate 基类<br/>命令层"]
B --> D["Migrate 类<br/>执行层"]
C --> E["迁移文件目录<br/>database/migrations 或各模块 data/migrations"]
D --> F["数据库适配器<br/>Phinx Adapter"]
F --> G["迁移日志表<br/>migration / {app}_migration / plugin_{name}_migration"]
```

图表来源
- [vendor/xia/migration/src/command/Migrate.php:30-33](file://vendor/xia/migration/src/command/Migrate.php#L30-L33)
- [vendor/xia/migration/src/Migrate.php:127-139](file://vendor/xia/migration/src/Migrate.php#L127-L139)
- [vendor/xia/migration/src/Migrate.php:103-111](file://vendor/xia/migration/src/Migrate.php#L103-L111)

章节来源
- [vendor/xia/migration/src/command/Migrate.php:30-33](file://vendor/xia/migration/src/command/Migrate.php#L30-L33)
- [vendor/xia/migration/src/Migrate.php:127-139](file://vendor/xia/migration/src/Migrate.php#L127-L139)
- [vendor/xia/migration/src/Migrate.php:103-111](file://vendor/xia/migration/src/Migrate.php#L103-L111)

## 核心组件
- 命令层（Command 层）
  - migrate:create：创建迁移文件模板
  - migrate:run：执行迁移（可按版本或日期）
  - migrate:rollback：回滚迁移（可按版本或日期，支持强制）
  - migrate:status：查看迁移状态（文本/JSON）
  - migrate:breakpoint：设置/清除断点，阻止越过断点的回滚
- 执行层（Migrate 类）
  - 统一解析迁移文件、构建适配器、执行迁移与回滚、记录日志
- 辅助工具
  - Creator：生成迁移文件模板并写入目标目录
  - Service：注册命令到 ThinkPHP 控制台

章节来源
- [vendor/xia/migration/src/command/migrate/Create.php:27-44](file://vendor/xia/migration/src/command/migrate/Create.php#L27-L44)
- [vendor/xia/migration/src/command/migrate/Run.php:29-46](file://vendor/xia/migration/src/command/migrate/Run.php#L29-L46)
- [vendor/xia/migration/src/command/migrate/Rollback.php:23-40](file://vendor/xia/migration/src/command/migrate/Rollback.php#L23-L40)
- [vendor/xia/migration/src/command/migrate/Status.php:22-34](file://vendor/xia/migration/src/command/migrate/Status.php#L22-L34)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:22-38](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L22-L38)
- [vendor/xia/migration/src/command/Migrate.php:23-24](file://vendor/xia/migration/src/command/Migrate.php#L23-L24)
- [vendor/xia/migration/src/Migrate.php:22-43](file://vendor/xia/migration/src/Migrate.php#L22-L43)
- [vendor/xia/migration/src/Creator.php:10-18](file://vendor/xia/migration/src/Creator.php#L10-L18)
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)

## 架构总览
迁移命令在 ThinkCMF 中的调用链路如下：

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant CLI as "Console 命令"
participant Cmd as "命令类<br/>Create/Run/Rollback/Status/Breakpoint"
participant Base as "Migrate 基类"
participant Exec as "Migrate 执行类"
participant FS as "迁移文件系统"
participant DB as "数据库适配器"
Dev->>CLI : 输入命令
CLI->>Cmd : 解析参数与选项
alt 创建迁移
Cmd->>FS : 写入迁移模板文件
Cmd-->>Dev : 输出创建结果
else 执行/回滚/状态/断点
Cmd->>Base : 获取迁移列表/版本日志
Base->>Exec : 初始化执行器
Exec->>FS : 加载迁移文件
Exec->>DB : 执行迁移/回滚/查询
DB-->>Exec : 返回执行结果
Exec-->>Cmd : 输出进度与耗时
Cmd-->>Dev : 输出最终结果
end
```

图表来源
- [vendor/xia/migration/src/command/migrate/Create.php:56-68](file://vendor/xia/migration/src/command/migrate/Create.php#L56-L68)
- [vendor/xia/migration/src/command/migrate/Run.php:57-89](file://vendor/xia/migration/src/command/migrate/Run.php#L57-L89)
- [vendor/xia/migration/src/command/migrate/Rollback.php:49-66](file://vendor/xia/migration/src/command/migrate/Rollback.php#L49-L66)
- [vendor/xia/migration/src/command/migrate/Status.php:43-53](file://vendor/xia/migration/src/command/migrate/Status.php#L43-L53)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:40-56](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L40-L56)
- [vendor/xia/migration/src/command/Migrate.php:96-149](file://vendor/xia/migration/src/command/Migrate.php#L96-L149)
- [vendor/xia/migration/src/Migrate.php:201-254](file://vendor/xia/migration/src/Migrate.php#L201-L254)

## 详细组件分析

### migrate:create：创建迁移
- 功能：生成迁移文件模板，自动命名并写入对应目录。
- 关键参数与选项
  - name：迁移类名（驼峰格式）
  - -a/--app：指定应用名称，生成到 {app}/data/migrations
  - -p/--plugin：指定插件名称，生成到 plugins/{plugin}/data/migrations
- 输出：打印“created”及相对路径
- 注意事项
  - 类名需符合 Phinx 命名规范；同名类或同版本重复会报错
  - 目标目录不存在或不可写将抛出异常

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析参数 name/-a/-p"]
Parse --> Validate["校验类名合法性"]
Validate --> |合法| EnsureDir["确保目标目录存在且可写"]
Validate --> |非法| Error["抛出异常"]
EnsureDir --> GenFile["生成迁移文件"]
GenFile --> Done(["完成"])
Error --> Done
```

图表来源
- [vendor/xia/migration/src/Creator.php:20-65](file://vendor/xia/migration/src/Creator.php#L20-L65)
- [vendor/xia/migration/src/command/migrate/Create.php:56-68](file://vendor/xia/migration/src/command/migrate/Create.php#L56-L68)

章节来源
- [vendor/xia/migration/src/command/migrate/Create.php:27-44](file://vendor/xia/migration/src/command/migrate/Create.php#L27-L44)
- [vendor/xia/migration/src/command/migrate/Create.php:56-68](file://vendor/xia/migration/src/command/migrate/Create.php#L56-L68)
- [vendor/xia/migration/src/Creator.php:20-65](file://vendor/xia/migration/src/Creator.php#L20-L65)

### migrate:run：执行迁移
- 功能：执行所有可用迁移，可选执行到指定版本或日期。
- 关键参数与选项
  - -t/--target：执行到指定版本号
  - -d/--date：执行到指定日期（格式 YYYYMMDD）
  - -a/--app：仅执行某应用迁移
  - -p/--plugin：仅执行某插件迁移
  - -v：详细输出
- 行为说明
  - 默认先执行 ThinkCMF 核心迁移，再遍历所有应用与插件迁移目录
  - 支持按版本或日期执行；失败时输出错误提示与数据库配置检查指引
- 输出：逐个迁移执行进度、耗时与“done”提示

```mermaid
sequenceDiagram
participant CLI as "命令行"
participant Run as "Run 命令"
participant Mig as "Migrate 执行器"
participant DB as "数据库"
CLI->>Run : 解析 -t/-d/-a/-p/-v
Run->>Mig : 初始化执行器(app/plugin为空则全量)
Mig->>DB : 迁移到目标版本或日期
DB-->>Mig : 执行结果
Mig-->>Run : 输出进度与耗时
Run-->>CLI : 输出完成信息
```

图表来源
- [vendor/xia/migration/src/command/migrate/Run.php:57-89](file://vendor/xia/migration/src/command/migrate/Run.php#L57-L89)
- [vendor/xia/migration/src/Migrate.php:291-340](file://vendor/xia/migration/src/Migrate.php#L291-L340)

章节来源
- [vendor/xia/migration/src/command/migrate/Run.php:29-46](file://vendor/xia/migration/src/command/migrate/Run.php#L29-L46)
- [vendor/xia/migration/src/command/migrate/Run.php:57-89](file://vendor/xia/migration/src/command/migrate/Run.php#L57-L89)
- [vendor/xia/migration/src/Migrate.php:291-340](file://vendor/xia/migration/src/Migrate.php#L291-L340)

### migrate:rollback：回滚迁移
- 功能：回滚到最后一个迁移或指定版本；支持按日期回滚；支持强制忽略断点。
- 关键参数与选项
  - -t/--target：回滚到指定版本号
  - -d/--date：回滚到指定日期
  - -f/--force：强制回滚（忽略断点）
  - -v：详细输出
- 行为说明
  - 若无已执行迁移，提示“无可回滚”
  - 指定版本不存在时提示“目标版本未找到”
  - 到达断点且未强制时停止回滚
  - 支持按日期回滚到最近的历史版本

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析 -t/-d/-f"]
Parse --> DateCheck{"是否指定日期？"}
DateCheck --> |是| ToDate["计算最早历史版本并回滚"]
DateCheck --> |否| Target["确定目标版本"]
Target --> Valid{"目标版本有效？"}
Valid --> |否| Warn["提示未找到版本"]
Valid --> |是| Break{"到达断点且未强制？"}
Break --> |是| Stop["停止回滚"]
Break --> |否| Down["逐个执行 DOWN 并记录日志"]
Down --> Done(["完成"])
ToDate --> Done
Warn --> Done
Stop --> Done
```

图表来源
- [vendor/xia/migration/src/command/migrate/Rollback.php:49-66](file://vendor/xia/migration/src/command/migrate/Rollback.php#L49-L66)
- [vendor/xia/migration/src/command/migrate/Rollback.php:68-119](file://vendor/xia/migration/src/command/migrate/Rollback.php#L68-L119)
- [vendor/xia/migration/src/command/migrate/Rollback.php:121-145](file://vendor/xia/migration/src/command/migrate/Rollback.php#L121-L145)

章节来源
- [vendor/xia/migration/src/command/migrate/Rollback.php:23-40](file://vendor/xia/migration/src/command/migrate/Rollback.php#L23-L40)
- [vendor/xia/migration/src/command/migrate/Rollback.php:49-66](file://vendor/xia/migration/src/command/migrate/Rollback.php#L49-L66)
- [vendor/xia/migration/src/command/migrate/Rollback.php:68-119](file://vendor/xia/migration/src/command/migrate/Rollback.php#L68-L119)
- [vendor/xia/migration/src/command/migrate/Rollback.php:121-145](file://vendor/xia/migration/src/command/migrate/Rollback.php#L121-L145)

### migrate:status：查看迁移状态
- 功能：列出所有迁移及其状态（up/down），支持 JSON 输出。
- 关键参数与选项
  - -f/--format：text 或 json，默认 text
- 输出要点
  - 显示“状态/迁移ID/开始时间/结束时间/迁移名称”
  - 若迁移记录缺失，标记“** MISSING **”
  - 断点版本会额外提示“BREAKPOINT SET”

```mermaid
sequenceDiagram
participant CLI as "命令行"
participant Status as "Status 命令"
participant Base as "Migrate 基类"
participant DB as "数据库"
CLI->>Status : 解析 -f
Status->>Base : 获取迁移列表与版本日志
Base->>DB : 查询版本日志
DB-->>Base : 返回版本日志
Base-->>Status : 返回迁移与日志
Status-->>CLI : 输出表格或 JSON
```

图表来源
- [vendor/xia/migration/src/command/migrate/Status.php:43-53](file://vendor/xia/migration/src/command/migrate/Status.php#L43-L53)
- [vendor/xia/migration/src/command/migrate/Status.php:55-123](file://vendor/xia/migration/src/command/migrate/Status.php#L55-L123)
- [vendor/xia/migration/src/command/Migrate.php:86-89](file://vendor/xia/migration/src/command/Migrate.php#L86-L89)

章节来源
- [vendor/xia/migration/src/command/migrate/Status.php:22-34](file://vendor/xia/migration/src/command/migrate/Status.php#L22-L34)
- [vendor/xia/migration/src/command/migrate/Status.php:43-53](file://vendor/xia/migration/src/command/migrate/Status.php#L43-L53)
- [vendor/xia/migration/src/command/migrate/Status.php:55-123](file://vendor/xia/migration/src/command/migrate/Status.php#L55-L123)

### migrate:breakpoint：断点管理
- 功能：对指定版本设置或清除断点，阻止越过断点的回滚；也可一键清除全部断点。
- 关键参数与选项
  - -t/--target：目标版本号（不指定则默认最新）
  - -r/--remove-all：清除全部断点
- 行为说明
  - 不允许同时设置断点与清除全部断点
  - 版本无效时输出警告
  - 成功后输出断点状态变更

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析 -t/-r"]
Parse --> Both{"同时设置与清除？"}
Both --> |是| Throw["抛出参数冲突异常"]
Both --> |否| RemoveAll{"是否清除全部？"}
RemoveAll --> |是| ClearAll["清除全部断点"]
RemoveAll --> |否| Toggle["切换目标版本断点"]
Toggle --> Done(["完成"])
ClearAll --> Done
Throw --> Done
```

图表来源
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:40-56](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L40-L56)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:58-82](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L58-L82)

章节来源
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:22-38](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L22-L38)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:40-56](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L40-L56)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:58-82](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L58-L82)

## 依赖关系分析
- 命令注册
  - Service 在 boot 阶段绑定 Creator 并注册迁移相关命令
  - 当前仓库中部分命令被注释，实际启用以安装包为准
- 命令与执行层耦合
  - 命令层通过基类 Migrate 获取迁移列表与版本日志
  - 执行层 Migrate 负责加载迁移文件、构造适配器、执行迁移/回滚、记录日志
- 外部依赖
  - Phinx 适配器工厂负责创建适配器并支持前缀包装
  - ThinkPHP 控制台输入/输出用于交互式反馈

```mermaid
graph LR
Svc["Service<br/>注册命令"] --> CmdCreate["Create 命令"]
Svc --> CmdRun["Run 命令"]
Svc --> CmdRoll["Rollback 命令"]
Svc --> CmdStatus["Status 命令"]
Svc --> CmdBP["Breakpoint 命令"]
CmdCreate --> Creator["Creator<br/>生成迁移文件"]
CmdRun --> Base["Migrate 基类"]
CmdRoll --> Base
CmdStatus --> Base
CmdBP --> Base
Base --> Exec["Migrate 执行类"]
Exec --> Adapter["Phinx 适配器"]
Exec --> DB["数据库"]
```

图表来源
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)
- [vendor/xia/migration/src/command/Migrate.php:96-149](file://vendor/xia/migration/src/command/Migrate.php#L96-L149)
- [vendor/xia/migration/src/Migrate.php:201-254](file://vendor/xia/migration/src/Migrate.php#L201-L254)

章节来源
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)
- [vendor/xia/migration/src/command/Migrate.php:96-149](file://vendor/xia/migration/src/command/Migrate.php#L96-L149)
- [vendor/xia/migration/src/Migrate.php:201-254](file://vendor/xia/migration/src/Migrate.php#L201-L254)

## 性能考量
- 批量执行
  - migrate:run 默认遍历核心、应用与插件迁移目录，建议在 CI/CD 中按模块分步执行，减少锁竞争
- 事务与回放
  - 执行层在适配器支持事务时自动开启事务，保证迁移原子性；change() 模式下使用代理适配器进行逆向回放
- 日志与耗时
  - 每个迁移执行前后输出耗时，便于定位慢迁移
- 版本顺序
  - 可通过数据库配置项控制版本顺序（创建时间或自然序），避免版本冲突

章节来源
- [vendor/xia/migration/src/command/Migrate.php:35-84](file://vendor/xia/migration/src/command/Migrate.php#L35-L84)
- [vendor/xia/migration/src/Migrate.php:141-189](file://vendor/xia/migration/src/Migrate.php#L141-L189)
- [vendor/xia/migration/src/Migrate.php:72-101](file://vendor/xia/migration/src/Migrate.php#L72-L101)

## 故障排查指南
- 常见错误与提示
  - “目标版本未找到”：检查版本号是否存在于迁移文件列表
  - “无可回滚”：确认是否存在已执行迁移或断点限制
  - “数据库配置错误”：运行 migrate:run 失败时，检查 data/config/database.php
  - “迁移目录不存在或不可写”：确保目标目录存在且具备写权限
- 排查步骤
  - 使用 migrate:status 查看当前状态与缺失记录
  - 使用 migrate:breakpoint 清除断点后重试回滚
  - 使用 migrate:run -v 查看详细输出定位问题
- 最佳实践
  - 先在测试环境验证迁移，再在生产执行
  - 对关键业务迁移设置断点，防止误回滚
  - 使用 -d 选项按日期精确控制执行范围

章节来源
- [vendor/xia/migration/src/command/migrate/Run.php:80-85](file://vendor/xia/migration/src/command/migrate/Run.php#L80-L85)
- [vendor/xia/migration/src/command/migrate/Rollback.php:77-81](file://vendor/xia/migration/src/command/migrate/Rollback.php#L77-L81)
- [vendor/xia/migration/src/command/migrate/Rollback.php:98-102](file://vendor/xia/migration/src/command/migrate/Rollback.php#L98-L102)
- [vendor/xia/migration/src/command/migrate/Status.php:94-102](file://vendor/xia/migration/src/command/migrate/Status.php#L94-L102)

## 结论
xia/migration 为 ThinkCMF 提供了完善的数据库迁移能力，覆盖创建、执行、回滚、状态与断点管理。通过模块化目录与统一适配器，既能满足核心迁移，也能扩展到应用与插件。建议在团队内建立标准化流程：先 status 校验，再 run 执行，必要时用 breakpoint 锚定关键版本，最后 rollback 时谨慎使用 -f。

## 附录

### 命令速查与示例
- 创建迁移
  - php think migrate:create CreateUsersTable
  - php think migrate:create Test -a demo
  - php think migrate:create Test -p Demo
- 执行迁移
  - php think migrate:run
  - php think migrate:run -t 20110103081132
  - php think migrate:run -d 20110103
  - php think migrate:run -v
- 回滚迁移
  - php think migrate:rollback
  - php think migrate:rollback -t 20111018185412
  - php think migrate:rollback -d 20111018
  - php think migrate:rollback -f
  - php think migrate:rollback -v
- 查看状态
  - php think migrate:status
  - php think migrate:status -f json
- 断点管理
  - php think migrate:breakpoint
  - php think migrate:breakpoint -t 20110103081132
  - php think migrate:breakpoint -r

章节来源
- [vendor/xia/migration/src/command/migrate/Create.php:35-44](file://vendor/xia/migration/src/command/migrate/Create.php#L35-L44)
- [vendor/xia/migration/src/command/migrate/Run.php:37-46](file://vendor/xia/migration/src/command/migrate/Run.php#L37-L46)
- [vendor/xia/migration/src/command/migrate/Rollback.php:30-39](file://vendor/xia/migration/src/command/migrate/Rollback.php#L30-L39)
- [vendor/xia/migration/src/command/migrate/Status.php:27-33](file://vendor/xia/migration/src/command/migrate/Status.php#L27-L33)
- [vendor/xia/migration/src/command/migrate/Breakpoint.php:28-37](file://vendor/xia/migration/src/command/migrate/Breakpoint.php#L28-L37)
- [AGENTS.MD:580-593](file://AGENTS.MD#L580-L593)

### 常见组合与场景
- 新增字段后快速上线
  - 步骤：migrate:create + migrate:run
  - 保障：先本地验证，再灰度执行
- 紧急回滚
  - 步骤：migrate:status → 确认断点 → migrate:rollback -f
  - 保障：仅在断点之后强制回滚，避免误伤
- 按日期回滚
  - 步骤：migrate:rollback -d 20250301
  - 保障：精确到秒级版本匹配
- 多模块迁移
  - 步骤：migrate:run -a app1；migrate:run -p pluginA
  - 保障：隔离执行，降低并发风险

章节来源
- [vendor/xia/migration/src/command/migrate/Run.php:68-131](file://vendor/xia/migration/src/command/migrate/Run.php#L68-L131)
- [vendor/xia/migration/src/command/migrate/Rollback.php:57-61](file://vendor/xia/migration/src/command/migrate/Rollback.php#L57-L61)