Phinx不能直接通过composer require安装后运行迁移，必须作为全局工具或开发依赖安装，并手动初始化配置和迁移目录；其命令需通过vendor/bin/phinx调用或配置PATH，且依赖PDO扩展、正确配置数据库参数及phinxlog表维护状态。
Phinx 不是“开箱即用就能自动解决所有迁移问题”的工具，它只是把迁移过程标准化了——真正省事的前提是你得按它的约定组织代码、理解它的生命周期，否则反而会卡在 phinx migrate 无反应、phinx rollback 报错或环境配置不生效上。
为什么 composer require robmorgan/phinx 后还不能直接跑迁移？
Phinx 需要一个明确的配置入口和迁移目录结构，Composer 只装了命令行可执行文件，但没生成 phinx.php 或 phinx.yml。没有配置，phinx status 会报 No migrations directory found。
- 必须手动运行
vendor/bin/phinx init（注意不是phinx，Windows 下可能是vendor\bin\phinx.bat）生成基础配置 -
phinx.php里默认只配了paths.migrations，但如果你用的是 MySQL，还得补全environments.development下的host、name、user、pass，漏一项就连接失败 - 配置里的
name是数据库名，不是表前缀；如果用的是 Docker 环境，host得填容器名（如mysql），不能写localhost
phinx create 生成的迁移文件为什么总缺字段或类型？
Phinx 默认生成的 PHP 类只留了空的 change 方法骨架，不会自动推断表结构。它不读取现有数据库，也不解析 ORM 模型，一切靠手写。
- 别依赖 IDE 自动生成方法体，
up()和down()必须显式定义，且down()逻辑要和up()严格对称，否则rollback会失败 - 添加字段用
$table->addColumn('status', 'enum', ['values' => ['active', 'inactive']])，但 MySQL 8.0+ 对 enum 大小写敏感，值数组必须全小写，否则迁移时抛SQLSTATE[42000] - 加索引别写
$table->addIndex(['user_id', 'created_at'])就完事——如果字段类型是TIMESTAMP，MySQL 要求指定长度（如created_at(6)），否则建索引失败
多环境切换时 phinx migrate -e production 为啥还是连测试库？
Phinx 读配置的优先级是：命令行参数 PHINX_* 环境变量 default_environment。如果环境变量 PHINX_ENVIRONMENT 已设置，-e 参数会被忽略。
- 检查是否在 shell 配置（如
~/.zshrc）里误设了export PHINX_ENVIRONMENT=testing，删掉或临时unset PHINX_ENVIRONMENT - 生产环境配置块里，
name字段必须和实际数据库名完全一致（包括下划线、大小写），Phinx 不做任何 normalize - 使用
phinx migrate -e production -c phinx.yml显式指定配置文件路径，避免因工作目录不同导致加载了错误的phinx.php
最常被跳过的环节是验证迁移文件命名格式：20240517102345_add_user_status.php 这类时间戳前缀必须是 14 位数字，少一位或含字母，phinx status 就直接过滤掉该文件——它不报错，只是假装看不见。
