🚀 Astro 內容网站开发路线图：从零到內容发布

本文檔提供了一个完整的开发路线图，指导您如何在 Cloudflare Pages 环境下，成功整合 Decap CMS 作为內容後端。

本路线图涵蓋了从 Astro 项目初始化到內容在网站上成功顯示的每一个关鍵步驟，方便大家在佈建网站时能夠可以依循參考。

概览：三階段开发流程

我们將流程分为三个核心階段，以解決最棘手的 OAuth 认证問题，並确保內容能被 Astro 正确渲染，分別为：

1. 結構初始化：建立项目結構、內容集合与 CMS 所需文件。
2. CMS 整合与 GitHub OAuth 认证：部署 Cloudflare Pages Functions 代理，配置 GitHub 认证密鑰，确保登入功能正常。
3. 內容渲染与发布：建立 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: githubrepo: Mountos/webbranch: mainbase_url: https://mountos.pages.devauth_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 渲染）已打通。