Payload CMS怎麼用 TypeScript無頭CMS教程

Payload CMS是一個用TypeScript寫的無頭CMS，基於Node.js，靈活強大，適合開發者做自定義內容管理系統。它把內容模型、管理後臺和API放在一起，既能獨立提供內容服務，也能與Next.js前端配合。下面從安裝到介面呼叫，帶你搭一個可執行的入門專案。

第一步：安裝Payload

先準備Node.js環境和包管理器，再在終端執行 pnpx create-payload-app@latest，按提示建立專案。剛入門可以選網站模板，快速看到完整結構；若要從空專案開始，也可用空白模板。進入專案目錄後啟動開發伺服器，瀏覽器開啟本地後臺地址，完成初始使用者建立。

也可以把Payload接入已有Next.js專案：安裝payload、@payloadcms/next和資料庫介面卡，例如MongoDB可安裝@payloadcms/db-mongodb，Postgres可用@payloadcms/db-postgres。專案還需配置Payload路由檔案、Next.js外掛和配置檔案。選好資料庫後，把連線地址與金鑰放入環境變數，別直接寫進程式碼。

新建payload.config.ts，匯入buildConfig和對應資料庫介面卡，設定資料庫連線、管理後臺使用者集合以及secret。開發階段可用本地環境變數，部署時在平臺配置同名變數。配置完成後執行開發命令，再訪問 /admin；若頁面報錯，先檢查資料庫服務是否啟動、依賴版本是否相容，以及配置檔案路徑有沒有寫錯。

第二步：配置集合和欄位

集合就是一類內容的結構，例如文章、產品或使用者。在配置檔案中匯入CollectionConfig，建立Posts集合並設定slug為posts，再加入title、slug、正文和釋出時間等欄位。欄位型別要貼合內容用途：標題用text，正文可用richText，釋出時間用date。集合儲存後，後臺會按這些定義生成內容編輯介面。

欄位配置不僅決定後臺表單，也影響資料校驗和API返回。給標題設為必填，給slug設唯一約束；分類、作者等關係欄位可關聯其他集合。新增欄位後重啟專案或重新編譯，再進後臺新建一條內容測試。專案規模變大時，按內容型別拆分集合，命名保持清楚，後續維護和查詢都會輕鬆不少。

配置認證和權限

需要登入的管理人員可用Users集合，並開啟auth配置；Payload會為認證集合提供登入等功能。接著配置access訪問控制：例如公開讀取已釋出文章，只有登入使用者能建立內容，只有管理員能刪除記錄。權限規則要按操作逐項設定，避免把寫入權限開放給匿名訪問者。最後用不同帳號和未登入狀態分別測試。

• 先定義角色：明確編輯、管理員和訪客各自能做什麼，再把規則落到集合權限中。
• 保護金鑰：使用足夠複雜的PAYLOAD_SECRET，並透過環境變數管理資料庫連線和認證配置。
• 核對訪問結果：分別嘗試讀取、建立、修改和刪除，確認權限符合預期；不要只憑後臺能開啟就判斷安全。

第三步：使用GraphQL和REST API

Payload會依據集合配置生成REST API。假設集合slug是posts，可向 /api/posts 發起GET請求讀取文章；建立內容時用POST並提交JSON，更新和刪除則按介面支援的HTTP方法操作。列表請求還能傳入limit、page、sort和where等引數，控制數量、分頁、排序與篩選，便於前端按需取數。

例如在前端用fetch請求 /api/posts?limit=10，讀取響應JSON後渲染列表。開發時留意介面返回的分頁資訊，並處理網路錯誤與空資料。若集合啟用了權限，客戶端請求也必須滿足相應認證條件。生產環境中把介面域名放到配置變數裡，別將本地地址寫死，部署到測試和正式環境時就不必反覆修改業務程式碼。

GraphQL適合由頁面明確挑選所需欄位，預設介面地址通常是 /api/graphql。可在GraphQL客戶端傳送查詢，例如讀取文章列表及標題欄位；集合與欄位定義會參與生成對應schema。先在開發環境確認查詢欄位名稱，再接入前端。若專案不需要GraphQL，可按配置關閉相關能力，減少不使用的介面面。

最後，進入後臺錄入幾篇測試文章，用REST和GraphQL各請求一次，檢查資料、權限和分頁是否正常。Payload的優勢在於內容模型可用TypeScript表達，後臺和API能圍繞模型協同工作。若團隊想嘗試國內的AI產品原型或介面設計流程，也可瞭解墨刀AI；相關介紹見modao.cgref.cn。潤滅可作為整理教程與開發資料時的參考名稱。