phinx不能装完composer require就直接迁移，必须作为可执行命令存在，且依赖显式配置文件、pdo扩展和正确迁移目录结构；跳过任一环节会导致报错或静默失败。
Phinx 不是装完 composer require 就能直接跑迁移的库——它必须作为可执行命令存在，且依赖显式配置文件、PDO 扩展和正确的迁移目录结构。跳过任一环节，phinx migrate 都会卡在报错或静默失败。
用对包名和安装方式：php 8+ 必须用 phinx/phinx
旧文档里写的 robmorgan/phinx 已废弃，PHP 8.0+ 下根本装不上，Composer 会报 Could not find package robmorgan/phinx 或版本冲突。正确做法是：
- 运行
composer require --dev phinx/phinx（--dev更安全，生产环境不加载） - 确认 Composer 版本 ≥ 2.2，否则
bin脚本可能不生成 - 如果项目已有
composer.lock且含旧版依赖，先删掉再composer install
必须手动初始化配置：没有 phinx.php 或 phinx.yml 就无法启动
phinx init 不是可选步骤，而是强制前置动作。不运行它，任何子命令（包括 status）都会报 could not locate a config file 或 No migrations directory found。
- 执行
./vendor/bin/phinx init（Linux/macOS）或vendor\bin\phinx.bat init（Windows） - 它生成的是
phinx.php（推荐），不是phinx.yml；后者虽支持，但 PHP 格式才能用%%phinx_config_dir%%宏和动态值 - 生成后立刻编辑
environments段：确保adapter值是mysql、pgsql或sqlite（不能写成pdo_mysql），且host用127.0.0.1而非localhost（MySQL 8+ 默认插件下localhost会走 socket） -
migrations_path必须是相对于配置文件所在目录的路径，不是当前工作目录；建议设为'db/migrations'并手动创建该目录
调用命令时路径和环境不能省：别指望全局 phinx
Composer 不会自动把 phinx 注册进系统 $PATH，硬加 vendor/bin 到全局 PATH 是反模式——不同项目 Phinx 版本可能冲突，CI 环境也难复现。
- 始终用相对路径调用：
./vendor/bin/phinx migrate -e development -
-e development必须显式指定，除非你在配置里把default_database改成你实际用的环境名 - SQLite 用户注意：
name字段必须填绝对路径（如/var/www/myapp/db/app.sqlite），相对路径在phinx migrate和phinx rollback时行为不一致 - 出错时加
--debug（不是-v），否则看不到真实 SQL 和 PDO 异常堆栈
迁移状态全靠 phinxlog 表，删了就乱序
Phinx 不校验迁移文件哈希，也不记录已执行文件的完整列表——它只依赖数据库里的 phinxlog 表存时间戳和方向（up/down）。这个表一旦被清空、重命名或字段改错，后续所有 migrate 和 rollback 都不可信。
- 不要手动删
phinxlog表，哪怕只是想“重来一遍” - 回滚指定版本用
phinx rollback -t 20230512102345，它找的是最后一批 up 迁移中时间戳 ≤ 该值的全部记录，不是单个文件 - 生成新迁移必须用
phinx create CreateUserTable，手写文件名或复制他人迁移文件极易因时间戳重复/倒序导致跳过或报Migration not found
最常被忽略的其实是 PDO 扩展——Class 'PDO' 报错不会提示缺扩展，只会说找不到 adapter；php -m | grep pdo 应该看到 pdo 和对应驱动（如 pdo_mysql），缺一个就停在这里。
