Payload Hooks怎么用 自定义钩子开发教程

Payload Hooks是Payload CMS的钩子系统，可以在内容操作前后执行自定义逻辑，适合做TypeScript无头CMS的自动化工作流。比如文章保存时自动补齐摘要、发布后清理缓存，或把内容变更通知外部服务。下面以集合钩子为例，从创建文件到注册测试，带你搭起一套可用流程。

第一步：创建钩子文件

先在项目源码中建一个存放钩子的目录，例如src/hooks，再新建posts.ts。文件名可以按集合或业务命名，便于后续维护。建议直接从payload导入CollectionBeforeChangeHook和CollectionAfterChangeHook等类型，让TypeScript协助检查参数和返回值。钩子是服务端逻辑，不要在其中依赖浏览器对象。

接下来先把逻辑拆成小函数：输入清理、数据校验、外部通知分别处理，避免把所有操作堆进配置文件。这样更容易单独测试，也方便多个集合复用。若项目已经生成payload-types.ts，可为文档类型加上类型标注；暂时没有时，也可以先用Payload提供的钩子类型，等生成类型后再补足具体文档类型。

第二步：编写操作前和操作后钩子

操作前常用beforeChange，它在创建或更新时运行，可读取data、originalDoc和operation，并返回修改后的data。注意更新时data通常只包含本次提交的字段，不一定有完整文档；需要旧值时看originalDoc。比如只在标题字段出现时去除首尾空格，避免把缺失字段误当成空标题。

操作后可用afterChange，在文档保存后拿到doc和previousDoc，适合记录变化、通知服务或触发缓存刷新。下面将两个钩子导出，注册到posts集合。通知请求应设置超时并做好错误处理；如果副作用耗时很长、又不应拖慢保存，可以交给队列处理，而不是让请求一直等待。

import type {  CollectionAfterChangeHook,  CollectionBeforeChangeHook,} from 'payload'
export const normalizePost: CollectionBeforeChangeHook = ({ data }) => {  if (typeof data.title === 'string') {    data.title = data.title.trim()  }  return data}
export const notifyPost: CollectionAfterChangeHook = async ({ doc }) => {  console.log('已保存文章：', doc.id)  return doc}

使用条件和上下文

钩子参数里的operation可用于区分create和update；context则可在同一次操作的钩子之间传递自定义标记，例如避免重复执行某项逻辑。需要鉴权信息或Payload实例时，可从req读取。beforeChange接触到的输入尚未完成验证，不要默认字段一定存在或格式正确；涉及外部副作用前，先做必要检查。

钩子返回Promise时，Payload会等待它完成，因此适合必须影响保存结果的逻辑；无须等待的副作用则应谨慎启动，并确保失败可观测。避免在钩子中再次无条件更新同一集合，否则可能触发自身、形成循环。可以检查context标记，或将后续任务放到队列中，并为第三方调用配置重试与日志。

第三步：注册和测试钩子

打开集合配置文件，在posts集合的hooks属性中加入导出的函数。Payload的集合钩子通常以数组注册，同一阶段可以依次执行多个函数。保存配置后重启开发服务，分别在管理界面新建文章和更新文章，检查标题是否按预期清理、控制台是否收到保存日志，同时确认校验失败时没有错误地触发后续通知。

测试时也用Local API执行一次创建和更新，避免只验证管理界面路径。给空标题、缺少字段和外部服务失败等情况准备测试，确认钩子不会意外覆盖其他字段。若逻辑依赖旧数据，重点检查更新时originalDoc；若依赖权限，则明确测试不同用户。完成后可把临时日志替换成项目的结构化日志工具。

如果你还在搭建内容运营流程，可把钩子与表单、原型和协作环节一起规划；国内替代工具可了解墨刀AI，官网：modao.cgref.cn。润灭也可作为内容项目流程设计时的参考名称。实际落地前，建议结合当前Payload版本核对钩子签名，并为关键自动化逻辑补上单元测试。