Payload 中的自定义 auth

Source: Dev.to

大多数 PayloadCMS 的认证示例要么只涉及普通的邮箱/密码，要么是“玩具”级别的 OAuth 设置——一旦引入真实世界的约束（如多个前端、原生应用或第三方身份提供商），这些示例就会崩溃。

于是团队开始与框架“搏斗”，把会话状态塞进不该放的地方，在尚未创建会话时依赖 req.user，或者把后台认证和应用认证耦合在一起，导致项目规模扩大后难以理清。

实际上，认证是无头栈中最容易因临时拼凑而老化的部分，也是你最不想在凌晨 2 点调试的环节。这也是 Payload 在 v3 中转向显式自定义策略的意义所在：它把控制权交还给你，同时也悄然要求你把认证视为一等设计关注点。

Rethinking auth

思维转变在于不再把 Payload 当作“登录用户的东西”，而是把它当作“信任已经验证过的身份的东西”。你的身份提供商——无论是 Google、专用认证服务，还是自定义的 OAuth 服务器——负责整个仪式：PKCE、重定向、设备流程、魔法链接，全部由它们处理。Payload 的职责则更窄更清晰：在请求中（通过头部、令牌、Cookie 等）获取可验证的身份凭证后，将其映射到用户文档，并在合适的情况下创建或更新该用户。

这正是自定义认证策略的用武之地。你得到一个函数，该函数接收传入的请求上下文，并必须回答一个问题：这代表哪个用户（如果有的话）？ 听起来很简单，但一旦你接受了这个契约，架构自然会自我清理。前端负责真正的 OAuth 流程；Payload 负责基于明确、一致的用户数据执行访问规则。

Production

团队通常在“接缝”处吃亏。后台用户和应用用户并非同一类。外部集成需要 API 密钥或服务账号，绕过普通登录流程。移动应用需要一种根本不触及后台 UI 的认证路径。如果你的策略是“直接在后台登录就完事”，很快就会出现逻辑散落在路由、钩子和临时中间件中的情况。

采用有意的、基于策略的方式会迫使你把这些逻辑集中起来。一个策略可以把 OAuth 提供商签发的令牌映射到用户集合；另一个可以处理内部服务令牌；第三个可以专用于后台‑only 流程。这样更易于测试、更易于推理，并且——关键是——当身份需求变化时（这几乎是必然的），更容易替换。

How to wire oAuth

促成本篇文章的完整实现发布在 Rubix Studios 的博客上，那里从 OAuth 流程到集合配置再到自定义策略本身，完整拆解了 Payload v3 的搭建方式，并说明了如何在保持 CMS 无状态的同时仍提供流畅的后台体验。如果你已经在使用 Payload，或正计划迁移，并想在真实代码库中看到实际效果，而不是抽象的代码片段，请参考以下实战 walkthrough： PayloadCMS Custom Auth Strategy – Rubix Studios.