本文檔提供了一個完整的開發路線圖，指導您如何在 Cloudflare Pages 環境下，成功整合 Decap CMS 作為內容後端。
本路線圖涵蓋了從 Astro 專案初始化到內容在網站上成功顯示的每一個關鍵步驟，方便大家在佈建網站時能夠可以依循參考。
概覽：三階段開發流程
我們將流程分為三個核心階段，以解決最棘手的 OAuth 認證問題，並確保內容能被 Astro 正確渲染，分別為：
- 結構初始化：建立專案結構、內容集合與 CMS 所需檔案。
- CMS 整合與 GitHub OAuth 認證：部署 Cloudflare Pages Functions 代理，配置 GitHub 認證密鑰，確保登入功能正常。
- 內容渲染與發布：建立 Astro 路由和頁面，將 CMS 寫入的內容正確顯示在網站上。
階段一：專案結構與初始化
此階段專注於為 Astro 和 Decap CMS 建立必要的工作環境。
1.1 專案與目錄初始化
- Astro 專案初始化： 在 Codespaces 或本地環境中運行 npm create astro@latest 創建新專案。
- CMS 靜態結構： 創建 /public/admin 資料夾，用於放置 CMS 介面檔案。
- Functions 結構： 創建 /functions 資料夾，用於放置 Cloudflare Pages Functions 程式碼。
1.2 定義內容集合 Schema
- 目標： 在 Astro 中定義您的文章資料格式。
- 操作： 創建 /src/content/config.ts，使用 defineCollection 定義 blog 集合的欄位（例如 title, date, draft），確保其與 CMS 的 config.yml 欄位一致。
階段二：Decap CMS 整合與 OAuth 認證（核心挑戰）
此階段是整個流程中最複雜的部分，確保 CMS 登入功能在 Cloudflare Pages 上能正常運作。
2.1 配置 CMS 介面檔案
- 文件放置： 在 /public/admin/ 中放置 index.html 和 config.yml。
- 關鍵修正 index.html： 必須移除所有對 netlify-identity-widget.js 的引用，避免 Netlify 污染。
2.2 設置 GitHub OAuth 應用程式
- 創建應用程式： 在 GitHub Developer Settings 中創建 OAuth App，並獲取 Client ID 和 Client Secret。
- 關鍵回撥 URL： GitHub OAuth App 的 Authorization callback URL 必須精確設定為您的 Pages Functions 認證端點，例如：https://Mountos.pages.dev/.netlify/functions/auth。
2.3 配置 Cloudflare 環境變數
- 目的： 保護 Client Secret，供 Functions 代理使用。
- 操作： 在 Cloudflare Pages 儀表板的環境變數中設定 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET。
2.4 部署 Functions 程式碼
- 實作代理： 將包含 OAuth 邏輯的 auth.js 檔案放置在 /functions 資料夾中。這個程式碼負責處理 GitHub 的重定向與 Token 交換。
2.5 最終修正 config.yml 認證配置
- 目的： 指導 CMS 呼叫正確的 Pages Functions 代理端點。
- 配置範例：
backend:
name: github
repo: Mountos/web
branch: main
base_url: https://mountos.pages.dev
auth_endpoint: /.netlify/functions/auth
2.6 Git 推送與部署
- 操作： 執行 git add .、git commit、git push。這將把 Functions 程式碼和 CMS 配置上線，並啟用 Functions。
階段三：內容渲染與發布
此階段是確保網站能夠讀取 CMS 寫入的內容並將其顯示出來。
3.1 撰寫並發布第一篇文章
- 驗證登入： 訪問 https://mountos.pages.dev/admin/ 成功登入 Decap CMS。
- 發布內容： 在 CMS 中撰寫並發布一篇文章，確認內容檔案已成功推送到 GitHub 倉庫的 src/content/blog/ 資料夾。
3.2 建立文章列表頁
- 路徑： /src/pages/blog/index.astro
- 功能： 使用 astro:content 的 getCollection(‘blog’) 讀取並列出所有已發布的文章標題。
3.3 建立單篇文章頁（動態路由）
- 路徑： /src/pages/blog/[…slug].astro
- 功能： 使用 getStaticPaths 根據文章的 slug 生成獨立頁面，並使用 entry.render() 渲染 Markdown 內容。
3.4 最終驗證
檢查： 重新部署網站後，訪問您的網站，確認文章列表與單篇文章頁面均可正常顯示，證明整個發布流程（CMS 寫入 -> GitHub 存儲 -> Cloudflare 部署 -> Astro 渲染）已打通。
發佈留言