guard认证器需preauthenticationguardtoken是因为其依赖令牌驱动机制：guardauthenticationlistener先将请求封装为该令牌并存入凭证，再交由guardauthenticationprovider触发supports()和getcredentials()；无此令牌则流程无法启动。
Guard认证器在 Symfony 5.3+ 已被标记为 deprecated，新项目应直接使用 AuthenticatorManager 体系（即继承 AbstractLoginFormAuthenticator 或实现 AuthenticatorInterface）；但如果你维护的是旧项目、或需理解其底层流转逻辑，必须清楚它不是“配个类就能跑”，而是依赖 GuardAuthenticationProvider 与 PreAuthenticationGuardToken 的协同调度。
Guard认证器为什么需要 PreAuthenticationGuardToken？
Guard 不是直接处理请求，而是靠令牌驱动。每次登录请求进来，GuardAuthenticationListener 会先封装成 PreAuthenticationGuardToken，里面存着原始凭证（比如 ['email' => 'a@b.c', 'password' => 'xxx']），再交给 GuardAuthenticationProvider 去匹配对应认证器。没有这个令牌中转，supports() 和 getCredentials() 就不会被触发。
常见错误现象：
- 表单 POST 到
/login却没进supports()—— 很可能防火墙没启用guard配置，或enable_authenticator_manager: false被误设 -
getUser()报Call to a member function loadUserByIdentifier() on null——UserProvider没在security.yaml的providers下注册，或认证器里没传入$userProvider
supports() 和 getCredentials() 的边界在哪？
supports() 只决定“是否由我处理”，不提取也不验证任何数据；getCredentials() 才真正从请求里捞字段。两者不能混用，否则会导致流程断裂。
典型写法：
public function supports(Request $request): bool
{
return $request->isMethod('POST') && $request->getPathInfo() === '/login';
}
public function getCredentials(Request $request): array
{
return [
'email' => $request->request->get('email'),
'password' => $request->request->get('password'),
];
}
注意点：
-
supports()里别调$request->request—— 此时 POST body 可能还没解析（尤其用了 JSON 或 multipart） -
getCredentials()返回的数组结构，要和getUser()、checkCredentials()里用的键名严格一致 - 如果登录页是 GET /login，而表单 POST 到 /api/login，则
supports()必须匹配后者路径，否则整个流程静默跳过
checkCredentials() 为什么不能自己 hash 密码？
它只负责比对，不负责加密。Symfony 的密码校验统一走 $this->userPasswordEncoder->isPasswordValid($user, $credentials['password'])。自己用 password_verify() 或 hash_equals() 是错的，会绕过框架的哈希策略（如自动升级 bcrypt cost factor）。
更关键的是：这个方法的返回值是布尔型，且仅此而已。不要在里面抛异常、重定向、或返回响应 —— 那些该由 onAuthenticationSuccess() 或 onAuthenticationFailure() 处理。
容易踩的坑：
- 在
checkCredentials()里调$this->getDoctrine()查库 —— 用户对象已由getUser()加载好了，重复查是冗余 - 返回字符串或
null而非true/false—— 框架会当成false，但调试时极难定位 - 忽略
$user可能是null——getUser()失败时传进来的就是null，需先判空再调isPasswordValid()
authenticator_manager 启用后 Guard 还生效吗？
不生效。一旦设了 enable_authenticator_manager: true，整个 Guard 流程就被绕过了。框架会转而寻找实现了 AuthenticatorInterface 的服务，并按 custom_authenticators 列表顺序执行 authenticate()。
这意味着：
- 旧 Guard 认证器类即使还存在，也不会被调用，除非你显式禁用
authenticator_manager -
security.yaml里同时写guard:和custom_authenticators:是冲突配置，后者优先 - 迁移时最常漏掉的一步：删掉
guard:块，把类名从AbstractGuardAuthenticator改成AbstractLoginFormAuthenticator，并更新onAuthenticationSuccess()的返回类型（现在必须返回Response|null）
真正的复杂点不在代码怎么写，而在“哪个配置开关控制哪条链路”——enable_authenticator_manager、firewalls.main.guard、firewalls.main.custom_authenticators 三者互斥，改错一个，整个认证就静默失效，连日志都不报错。
