php webman migrate 命令可用的前提是正确集成x2nx/webman-migrate插件、phinx.yml配置生效且environment名严格小写；否则会静默失败或连错库。
php webman migrate 命令能用，但前提是插件已正确集成、phinx.yml 配置生效、且环境名严格小写——否则命令会静默失败或连错库。
为什么 php webman migrate 不执行或报错
Webman 本身不内置迁移能力，依赖 x2nx/webman-migrate 插件桥接 Phinx。常见失败不是命令不存在，而是底层配置未被识别：
-
config/plugin/x2nx/webman-migrate/app.php中'driver' => 'phinx'缺失或拼错，插件会 fallback 到空实现 - 项目根目录没有
phinx.yml（注意：不是phinx.php），Phinx 默认完全忽略 PHP 格式配置 -
environments下写了Development或PRODUCTION，Phinx 只认小写development/production - Docker 环境中
host: localhost导致连接拒绝——容器内localhost指自身，应填数据库服务容器名（如mysql）
php vendor/bin/phinx create 生成的文件不被识别
Webman 插件默认只扫描 database/migrations 目录，且要求文件名含完整时间戳前缀（如 20260526120000_create_users_table.php）。手动创建或重命名会破坏识别逻辑：
- 必须用
php vendor/bin/phinx create CreateUsersTable生成，不能手建空类 - 类名必须与文件名后缀一致（
CreateUsersTable），且继承Phinx\Migration\AbstractMigration - 若改过
phinx.yml中的migrations路径（如设为db/migrations），需同步在插件配置中声明：'migrations_path' => 'db/migrations' - 文件里用
change()方法没问题，但 Webman 插件对up()/down()兼容性更稳，尤其涉及字段重命名等操作时
php webman migrate 执行后表没创建，但 phinxlog 有记录
这说明 Phinx 认为迁移“成功”了，但 SQL 实际未生效——通常是权限或语法问题：
- MySQL 用户缺少
CREATE TABLE权限（不只是SELECT），检查GRANT语句是否包含ALL PRIVILEGES ON `dbname`.* - 迁移中用了
ENUM或JSON类型，而目标 MySQL 版本不支持（如 MySQL 5.6 不支持 JSON） -
charset和collation在phinx.yml里没显式声明，某些环境会退化为latin1，导致建表语句被截断 - 执行时加
--dry-run参数验证：php vendor/bin/phinx migrate -e development --dry-run，看输出的 SQL 是否符合预期
生产环境回滚前必须确认的三件事
Phinx 的 rollback 在生产库上是高危操作，php webman migrate:rollback 并不等价于开发环境的“撤销”：
立即学习“PHP免费学习笔记（深入）”；
- 确保
down()方法真正可逆——比如addColumn('status', 'string')的逆操作不是删字段，而是清空+删列，但若该列已有业务数据，回滚会丢失 - 检查
phinxlog表是否在生产库中存在且可写；如果之前是手动建表或跨库迁移，该表可能缺失 - Webman 插件默认不支持
--step=2这类精细回滚，只能整批撤回，务必先在预发环境用相同数据集跑通全流程
