应使用 composer require phinx/phinx 安装，旧包名 robmorgan/phinx 已废弃；PHP 8+ 必须用 v0.15.0+ 版本；执行命令需用 ./vendor/bin/phinx；迁移文件须严格遵循命名、路径与类定义约定。
Composer 安装 Phinx 失败：找不到包或版本冲突
Phinx 不在 Packagist 默认托管的主仓库里，直接 composer require robmorgan/phinx 会报 Could not find package robmorgan/phinx 或提示版本不兼容。这不是你网络或 Composer 配置的问题，而是官方早已将 Phinx 迁移至新命名空间。
- 必须用新包名：
composer require phinx/phinx（旧robmorgan/phinx已废弃，PHP 8+ 下无法安装） - 如果你的项目 PHP 版本是 8.0+，别试
v0.12.x—— 它只支持到 PHP 7.4；得用v0.15.0+，且需确认 Composer 自身版本 ≥ 2.2 - 如果已有旧版锁文件（
composer.lock），先删掉再composer install，否则可能卡在依赖解析阶段
安装后执行 phinx 命令提示“command not found”
Composer 默认把可执行脚本装进 vendor/bin/，但这个路径通常不在系统 $PATH 里。不是 Phinx 没装好，是终端根本没找到它。
- 优先用相对路径运行：
./vendor/bin/phinx（Linux/macOS）或vendor\bin\phinx.bat（Windows） - 不想每次敲全路径？把
vendor/bin加进 shell 的$PATH，但注意：开发机可以，CI/CD 环境别硬依赖全局 PATH，应显式调用 - 别用
composer global require phinx/phinx—— 全局安装容易和不同项目的 PHP 版本、扩展冲突，尤其当多个项目需要不同 Phinx 版本时
初始化配置时 phinx init 报错：找不到 phinx.yml 或数据库驱动缺失
phinx init 只生成骨架配置，不校验数据库连接。常见报错如 Class 'PDO' not found 或 Driver "mysql" not supported，本质是 PHP 缺少对应扩展，不是 Phinx 配置写错了。
- 先确认 PHP CLI 模式已启用扩展：
php -m | grep -E "pdo|mysql|pgsql"；XAMPP/MAMP 用户常忽略 CLI 和 Web 使用不同 php.ini -
phinx.yml里的adapter必须小写且拼写准确：mysql、pgsql、sqlite—— 写成MySQL或pdo_mysql都会失败 - SQLite 路径要写绝对路径或相对于
phinx.yml的相对路径，比如name: ./data/app.db，不能只写name: app.db（默认找当前工作目录，而你可能在项目根目录下运行命令）
迁移执行时报 Migration class not found 或方法签名不匹配
Phinx 对迁移类的命名、位置、方法定义极其敏感。报这个错，90% 是文件结构或类定义没对上它的反射规则，而不是代码逻辑问题。
- 迁移文件必须放在
migrations/目录下（路径由phinx.yml的migrations_path控制），且文件名格式为YYYYMMDDHHIISS_描述.php，例如20231015123000_create_users_table.php - 类名必须与文件名前缀一致（不含下划线和时间戳），并继承
Phinx\Migration\AbstractMigration；方法必须是up()和down()，参数只能是Phinx\Db\Adapter\AdapterInterface类型 - 别在迁移里用
use App\Models\User;这类应用层类 —— 迁移应完全独立于业务代码，否则部署到无 autoload 的环境（如某些 Docker 镜像）会直接失败
Phinx 的“约定大于配置”很彻底，但这些约定藏在文档角落里。最易被忽略的是：CLI 运行时的当前工作目录决定配置加载路径和迁移文件查找起点，不是 composer.json 所在目录，也不是 vendor/bin/phinx 所在目录。
