新手在 symfony 4 首次做数据库迁移，关键在于手动确认四点：一是实体类需含 #[orm\entity] 注解且路径匹配；二是运行 doctrine:mapping:info 确保被识别；三是用 doctrine:database:create 和 debug:config doctrine 验证数据库连接；四是执行 doctrine:schema:update --dump-sql 查变化后再生成迁移，并首次运行 doctrine:migrations:sync-metadata-storage 初始化元数据表。
新手在 Symfony 4 第一次做数据库模型迁移，核心不是“怎么敲命令”，而是避免踩进配置错、识别不到、执行无声无息的坑。重点不在流程多复杂，而在几个关键节点必须手动确认。
确保实体类被 Doctrine 正确识别
Doctrine 不会自动扫描所有 PHP 类——它只认带 @ORM\Entity 或 PHP 8.1+ 的 #[ORM\Entity] 注解、且路径和命名空间严格匹配的类。
- 检查你的实体文件（如
src/Entity/User.php）开头是否有#[ORM\Entity]或@ORM\Entity() - 确认
config/packages/doctrine.yaml中mappings配置包含App\Entity\目录（默认已配好，但别手改删掉） - 运行
php bin/console doctrine:mapping:info，输出里必须看到你的实体类名；如果为空或没列出，迁移一定生成不了
先验证数据库连接是否真正生效
迁移命令不会报“连不上库”，而是静默失败或提示 DriverException。必须主动验证：
- 检查
.env文件中的DATABASE_URL是否指向可写库（例如sqlite:///%kernel.project_dir%/var/data.db或mysql://user:pass@127.0.0.1:3306/myapp） - 运行
php bin/console doctrine:database:create --if-not-exists，成功说明连接通、权限够 - 再跑
php bin/console debug:config doctrine，确认connections.default.url输出和你预期一致，且driver是pdo_sqlite或pdo_mysql
生成迁移前，先看 Doctrine 认为“有没有变化”
别急着 make:migration 或 doctrine:migrations:diff，先让 Doctrine 告诉你它看到了什么：
- 执行
php bin/console doctrine:schema:update --dump-sql，如果输出为空，说明 Doctrine 认为当前实体和数据库结构完全一致——那迁移自然为空 - 如果输出有 SQL，再运行
php bin/console make:migration（推荐）或php bin/console doctrine:migrations:diff - 生成后立刻打开
migrations/Version*.php，确认up()方法里有$this->addSql(...)调用，且语句非空；若为空，说明实体未被识别或数据库已有对应结构
第一次执行迁移要手动初始化元数据表
Symfony 4 默认使用 Doctrine Migrations v2+，首次运行迁移前需确保 doctrine_migration_versions 表存在并可写：
- 运行
php bin/console doctrine:migrations:sync-metadata-storage（仅首次需要） - 再执行
php bin/console doctrine:migrations:migrate - 如果提示
No migrations to execute，查一下数据库里是否存在doctrine_migration_versions表；若不存在或为空，说明上一步没做或失败了
