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版本核對鉤子簽名，併為關鍵自動化邏輯補上單元測試。