根本原因是migrate只比对migrations表记录而不校验物理表，若手动建表或导入SQL后未更新migrations表，会导致重复执行报“表已存在”；migrate:status仅反映记录状态，不保证结构一致。
为什么 migrate:status 显示已迁移但执行 migrate 仍报“表已存在”
根本原因不是迁移命令本身出错，而是 migrate 默认不检查数据库实际结构，只比对 migrations 表里的记录。如果某次迁移失败后手动建了表，或直接导入了 SQL，migrations 表里没写入对应记录，下次运行 migrate 就会试图重复执行——触发 SQLSTATE[42S01]: Base table or view already exists 错误。
这时 migrate:status 看起来“正常”，是因为它只查 migrations 表，不校验物理表是否存在。
-
migrate:status输出中某条记录状态为Ran，不代表对应表一定存在；状态为Not yet run，也不代表表一定不存在 - Hyperf 的
migrate命令不会自动跳过已存在的表，也不会提示“检测到表存在，是否跳过？” - 常见于本地开发环境手动改表、测试库还原、或团队协作中有人绕过迁移直接 DDL 操作
用 migrate:status 定位具体哪条迁移出问题
先运行 php bin/hyperf.php migrate:status，观察输出中最后几行。重点看两处：
- 最后一行标记为
Not yet run的迁移文件名（比如2023_05_10_142345_create_users_table.php） - 它前一行如果是
Ran，但你确认users表已经存在，就说明问题出在这里 - 如果该文件对应的表确实存在，但状态是
Not yet run，说明迁移记录缺失，需要手动补录
别只盯着“有红色报错”的那一行——错误往往藏在“看起来没问题”的那条迁移里。
手动修复迁移记录的三种方式及适用场景
目标是让 migrations 表与数据库实际状态一致。选哪种方式取决于你是否信任当前表结构：
- 如果表结构完全符合迁移文件预期（比如你刚手动执行过其中的
CREATE TABLE），运行：php bin/hyperf.php migrate:mark-as-ran 2023_05_10_142345_create_users_table - 如果表存在但结构不完整（比如缺字段、索引），先
DROP TABLE users，再运行migrate让框架重建 - 如果不想删表又不确定结构是否匹配，进数据库手动插入记录：
INSERT INTO migrations (migration, batch) VALUES ('2023_05_10_142345_create_users_table', 1);—— 注意batch值要和上一条Ran记录一致，否则后续迁移可能乱序
避免再次踩坑的关键配置和习惯
Hyperf 默认没有开启迁移前的表存在性检查，也不能自动回滚失败迁移。真正能防住问题的是流程和配置：
- 开发环境强制使用
--pretend参数预览将执行的 SQL：php bin/hyperf.php migrate --pretend，确认无误再执行 - 在
config/autoload/database.php的options中加入PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION，让底层错误不被静默吞掉 - 禁止任何人在非迁移途径下操作生产表结构；本地调试如需清库，统一用
migrate:fresh而非手动DROP -
migrate:status不是验证工具，只是快照。真要校验一致性，得写脚本比对migrations表和information_schema.tables
最麻烦的情况不是报错，而是没人知道表和迁移记录早已脱节——等上线才发现唯一索引缺失或者字段类型不对，那时再修就不是加一条记录的事了。
