loaduserbyidentifier() 返回 null 会直接抛出“user not found”异常，必须返回 userinterface 实例或明确抛出 usernamenotfoundexception；supportsclass() 必须严格匹配用户类名，否则提供者被跳过；refreshuser() 必须返回同类型实例；启用自定义 provider 需设置 enable_authenticator_manager: true。
loadUserByIdentifier() 返回 null 就会直接报 “User not found”
这个方法是自定义用户提供者的命门，不是可选逻辑。只要它返回 null 或抛出异常（比如 API 调用失败没兜底），Symfony 就会中断认证流程，抛出 AuthenticationException: User "xxx" not found. ——哪怕你外部系统里用户明明存在。
常见错误包括：
- 把表单提交的
email当成数据库主键去查，而实际要调用的是第三方接口，参数名可能是username或account_id - HTTP 请求失败时没 catch，直接让异常穿透出去
- 接口返回了用户数据，但忘了包装成实现了
UserInterface的对象（比如只 return ['email' => 'a@b.c']）
正确做法是：确保无论成功或失败，都返回一个 UserInterface 实例或明确 throw 新的 UsernameNotFoundException（别 throw 通用 Exception）。
supportsClass() 写错会导致整个提供者被跳过
这个方法不是装饰用的，它是 Symfony 决定“该不该用你的提供者”的开关。如果返回 false，框架压根不会调用你的 loadUserByIdentifier()，也不会报错，只会静默 fallback 到下一个 provider（如果有）或者直接失败。
必须严格匹配你实际返回的用户类：
- 如果你的用户类叫
App\Security\ApiUser，就得写return $class === ApiUser::class; - 不能写
return is_subclass_of($class, UserInterface::class);—— 这样所有实现都满足，但 Symfony 会因类型不明确拒绝加载 - 不能漏掉这行，也不能写成
return true;（旧文档坑人，新版会校验失败）
调试时最简单的方式：在 supportsClass() 里加 dump($class); die;，看进来的到底是什么类名。
refreshUser() 不只是“再查一次”，它必须返回同类型实例
这个方法在 session 刷新、Remember Me 激活、或 Guard 认证器重载用户时触发。很多人以为它只是个缓存更新钩子，其实它承担着类型守门员角色。
关键约束：
- 输入参数
$user是你之前loadUserByIdentifier()返回的那个对象，类型必须和supportsClass()声明的一致 - 返回值也必须是同一个类的实例（不能 new 一个新类，也不能 return $user->toArray()）
- 如果用户数据源是只读 API，这里通常就直接
return $user;，不用查
一旦返回类型不一致（比如返回了 stdClass），Symfony 会在后续密码校验前就抛出类型错误，堆栈里可能只显示 “Argument #1 passed to checkCredentials() must be instance of UserInterface”。
provider 配置写在 security.yaml 里但没生效？检查 enable_authenticator_manager
从 Symfony 6.2 开始，custom_authenticators 和自定义 provider 必须配合 enable_authenticator_manager: true 才能工作。旧式配置（form_login + providers）在开启新认证管理器后会被忽略。
典型配置片段：
security:
enable_authenticator_manager: true
providers:
app_user_provider:
id: App\Security\ApiUserProvider
firewalls:
main:
custom_authenticators:
- App\Security\LoginFormAuthenticator
provider: app_user_provider
漏掉第一行，你的 ApiUserProvider 就算写得再对，也永远不会被调用——因为整个认证链走的是旧的 DaoAuthenticationProvider 路径，它根本不认识你注册的 service ID。
最容易被忽略的点：loadUserByIdentifier() 的参数名是 $identifier，但它实际传入的值来自登录表单的 username 字段（不管字段叫 email 还是 phone），不是数据库 ID；而 refreshUser() 的健壮性，往往比 loadUserByIdentifier() 更难测到——它只在 session 过期后自动触发，本地开发容易误判为“没问题”。
