Doctrine注解需正确配置AnnotationReader并声明use Doctrine\ORM\Mapping as ORM；@ORM\Entity与@ORM\Table须成对出现；字符串值用双引号；doctrine/annotations必须为^2.0以兼容PHPDoc注解。
Doctrine 注解在 PHP 实体里怎么写才不报错
直接写 @ORM\Entity 或 @ORM\Column 却提示 “Unknown annotation”？不是语法错了，是没启用注解解析器。Doctrine 默认不自动扫描注解，必须显式配置 AnnotationReader，且 PHP 文件里得有正确的 use 声明。
- 每个用注解的实体文件顶部必须加：
use Doctrine\ORM\Mapping as ORM; -
@ORM\Entity和@ORM\Table必须成对出现（哪怕@ORM\Table参数为空），否则部分版本会跳过该类 - 注解里的字符串值要用双引号，比如
@ORM\Column(type="string", length=255)—— 单引号或不加引号（length=255可以，但type=string会报错） - 如果用了自定义命名空间（如
@MyApp\Annotations\SoftDelete），得手动注册到AnnotationRegistry::registerFile()或通过 Composer autoload 加载
doctrine/common 与 doctrine/annotations 版本冲突怎么办
PHP 8+ 项目装了 doctrine/orm:^3.0，却跑出 AttributeNotFoundException 或注解全被忽略？大概率是 doctrine/annotations 版本太高（v3.x），而旧版 doctrine/common（v3.x 之前）根本不认识 PHP 8 的原生 Attribute 语法。
- Doctrine ORM v3+ 要求
doctrine/annotations:^2.0，不是 ^3.0 —— v3.x 已移除对传统 PHPDoc 注解的支持，只处理 Attribute - 检查
composer show doctrine/annotations，如果是 3.x，执行：composer require doctrine/annotations:^2.0 - 若项目已混用 PHP 8 Attribute（如
#[ORM\Entity]）和传统注解（@ORM\Entity），必须统一：ORM v3 不支持混用，且默认只认 Attribute；要继续用 PHPDoc 注解，就得锁死doctrine/annotations:^2.0并确保AnnotationReader实例被正确传入EntityManager
@ORM\ManyToOne 关联字段为什么总 null，不加载关联数据
写了 @ORM\ManyToOne(targetEntity="User")，也生成了外键字段，但查出来关联对象一直是 null？这不是注解写错了，是 Doctrine 默认懒加载（lazy），且没触发代理初始化。
- 确认关联属性声明为
public或protected（不能private），且类型提示写对了，比如：/** @ORM\ManyToOne(targetEntity="App\Entity\User") */ protected ?User $owner = null; - 懒加载需要代理类，必须开启
proxy_autogenerate: true（开发环境）或提前生成（php bin/console doctrine:orm:generate-proxies） - 如果只是想立刻取数据，别依赖魔术 __get，改用
$entity->getOwner()（前提是 getter 存在且没被覆盖）；或者显式 join：$qb->join('e.owner', 'u') - 注意
fetch="EAGER"是反模式，容易 N+1，仅限极简场景临时用
注解映射和 YAML/XML 配置能混用吗
可以，但 Doctrine 不会自动合并 —— 它只读一种来源。一旦你在实体类里写了任何 @ORM\* 注解，整个类就进入“注解驱动模式”，YAML 或 XML 里同名实体的配置会被完全忽略。
立即学习“PHP免费学习笔记（深入）”；
- 混合使用只在迁移期可行：先把老配置转成注解，再删 YAML 文件；不要一边写注解、一边维护 XML
- 全局配置（如
auto_mapping: true）仍生效，但它只控制“哪些命名空间自动扫描”，不干预单个实体用什么方式映射 - 如果某实体想绕过注解（比如测试时临时换表名），只能用运行时元数据扩展（
SettableMetadataFactory），不能靠配置文件覆盖
注解看着省事，但隐式依赖太多：autoloader、annotation reader、proxy 机制、PHP 版本兼容性……漏掉其中一环，错误信息往往不指向真实原因。
