doctrine:migrations:diff生成空文件的根本原因是未检测到结构差异，常见于实体缺少@orm\entity/@orm\table注解、字段未配@orm\column、数据库与实体定义完全一致、连接配置错误或id策略变更未触发同步。
doctrine:migrations:diff 生成空文件的常见原因
根本不是 Doctrine 坏了，而是它没发现“值得生成迁移”的变化。最常踩的坑是：实体改了但没被 Doctrine 看见，或者数据库结构和实体实际一致，压根不需要变更。
- 实体类缺少
@ORM\Entity或@ORM\Table注解——Doctrine 会直接跳过该类，不参与 diff - 字段加了但没配
@ORM\Column（比如只写了private string $name;，没加注解），Doctrine 当它不存在 - 数据库里字段已存在，且类型、长度、nullable 等属性和实体定义完全一致——diff 结果就是“无变更”
- 用了
make:entity但没选“yes”确认生成 getter/setter，导致 Doctrine 无法正确反射属性（尤其在 PHP 8.2+ 属性提升场景下更敏感） - 连接配置指向了错误数据库（比如本地开发连的是 test_db，而你改的是 dev_db）——
doctrine:migrations:diff默认只查default连接
如何快速验证实体是否被 Doctrine 正确识别
别猜，用命令直接看 Doctrine 解析出的元数据：
php bin/console doctrine:debug:entity YourEntity
如果报错 Class "YourEntity" does not exist 或输出里没有你刚加的字段，说明注解、命名空间或自动加载出了问题。重点检查：
-
use Doctrine\ORM\Mapping as ORM;是否在文件顶部 - 类名和文件路径是否匹配（如
src/Entity/User.php→App\Entity\User） - 运行
composer dump-autoload强制刷新自动加载（尤其改完命名空间后）
PostgreSQL 下 ID 字段改动常被忽略
如果你改了主键策略（比如从 strategy="SEQUENCE" 改成 strategy="IDENTITY"），doctrine:migrations:diff 很可能不生成任何 SQL——因为 Doctrine 认为这只是“元数据描述变更”，不触发结构同步。
这种情况下必须手动干预：
- 先确认数据库中当前 id 列是否真是
GENERATED BY DEFAULT AS IDENTITY（用\d your_table查） - 如果还是
nextval('seq'::regclass)，说明旧序列还在起作用，Doctrine 不会主动替换成 identity - 此时需手写迁移：在
up()中执行ALTER TABLE your_table ALTER COLUMN id TYPE INTEGER GENERATED BY DEFAULT AS IDENTITY（PostgreSQL 10+） - 并确保对应实体已改为
#[ORM\GeneratedValue(strategy: 'IDENTITY')]，否则下次 diff 还会试图“修复”回序列
多环境或多数据库时 diff 失效
默认 doctrine:migrations:diff 只比对 default EntityManager。如果你在 config/packages/doctrine.yaml 里定义了多个连接（比如 customer_connection），却忘了指定上下文：
php bin/console doctrine:migrations:diff --em=customer_manager
否则它永远只看你默认库的结构，改了其他库的实体也白搭。另外注意：
-
--db参数不能替代--em；它只换数据库连接串，不换 EntityManager 配置 - Bundle 内部实体（比如第三方 Bundle 提供的）默认不参与 diff，除非你显式启用了
auto_mapping: true并把它们纳入扫描路径
ID 策略变更和 EntityManager 上下文错配，是 Symfony 7.1 下空迁移最隐蔽也最常被忽略的两个点——前者看起来像配置生效了，后者根本不会报错，只安静地什么也不做。
