Symfony 7.4.21 是当前稳定且推荐用于新项目的版本，原生深度集成 Doctrine ORM，支持属性定义实体、自动化迁移、自动仓储及查询优化。
Symfony 7.4.21 是当前稳定且推荐用于新项目的版本（截至 2026 年 10 月），它原生深度集成 Doctrine ORM，无需额外适配即可开箱使用。搭建过程已高度自动化，关键在于理解默认约定与可定制点。
安装与项目初始化
使用 Symfony CLI 创建带 Doctrine 的全新项目：
- 运行
symfony new myapp --version=7.4 --webapp（--webapp自动包含 Doctrine、Twig、WebProfiler 等常用组件） - 或用 Composer：
composer create-project symfony/skeleton myapp，再执行composer require orm—— 该命令会自动安装doctrine/doctrine-bundle、doctrine/orm及其依赖（如doctrine/dbal、doctrine/persistence） - 数据库连接配置统一写在
.env文件中，例如：DATABASE_URL="mysql://db_user:db_pass@127.0.0.1:3306/myapp?serverVersion=8.0"
实体定义与数据库迁移
Doctrine 推荐使用属性（PHP 8.1+）方式定义实体，语义清晰、无冗余注解：
- 运行
php bin/console make:entity User，交互式生成类文件（位于src/Entity/） - 实体示例（含主键、字段、关联）：
#[Entity]
class User
{
#[Id, GeneratedValue, Column(type: 'integer')]
public int $id;
<pre class="brush:php;toolbar:false;">#[Column(length: 180, unique: true)]
public string $email;
#[Column(type: 'json')]
public array $roles = [];
#[OneToMany(mappedBy: 'author', targetEntity: Post::class)]
public Collection $posts;}
- 生成迁移文件：
php bin/console doctrine:migrations:diff - 执行迁移：
php bin/console doctrine:migrations:migrate
仓储与查询实践
默认启用自动仓储（Repository 类可选），查询应优先使用 Repository 方法而非原始 DQL：
- 为
User创建仓储：php bin/console make:repository User - 在仓储中添加类型安全方法：
public function findActiveUsers(): array
{
return $this->createQueryBuilder('u')
->where('u.roles LIKE :role')
->setParameter('role', '%ROLE_USER%')
->getQuery()
->getResult();
}- 控制器中注入并调用：
public function index(UserRepository $users): Response { ... } - 复杂查询可结合 Doctrine 的
Eager Loading（fetch="EAGER"或join）避免 N+1 问题
性能与调试辅助
Symfony 7.4 提供开箱即用的优化机制和可观测能力：
- 启用查询缓存：在
config/packages/doctrine.yaml中设置query_cache_driver: pool，并配置对应缓存池（如cache.app） - 开发环境启用 Web Profiler，查看“Doctrine”面板可实时看到 SQL 执行次数、慢查询、未索引字段提示
- 使用
php bin/console doctrine:query:sql "SELECT * FROM user LIMIT 5"快速验证底层 SQL - 生产环境建议配合 Varnish 或反向代理启用 HTTP 缓存，Doctrine 层专注数据一致性
