用落筆一鍵發佈博客：Hugo、GitHub 與 Cloudflare Pages 搭建指南

這是一份面向普通用戶的博客搭建教程。完成後，你可以在落筆中寫作，並把文章一鍵發佈到自己的 GitHub + Hugo + Cloudflare Pages 博客。01|這套方案最終能做什麼完成一次初始化後，日常發佈只需要：在落筆中寫完或修改文章；點擊“發佈到博客”或“更新”；落筆把文章推送到自己的 GitHub 博客倉庫；Cloudflare Pages 自動構建並更新網站。第一次搭建需要配置賬號和授權；之後不需要再手工操作 GitHub 或 Cloudflare。02|一、整體架構flowchart LR A["落筆：寫作與發佈入口"] --> B["GitHub：博客源碼倉庫"] B --> C["Cloudflare Pages：自動構建與託管"] C --> D["pages.dev 或自定義域名"] E["Hugo：靜態網站生成器"] --> C B --> E四個部分各自負責不同工作：部分作用Hugo把 Markdown 文章、主題和配置文件生成靜態網站GitHub保存博客源碼、文章、圖片和版本歷史Cloudflare Pages監聽 GitHub，在代碼變化後自動運行 Hugo 並託管網站落筆提供寫作、文章整理和“一鍵發佈到博客”的入口發佈數據流落筆中的 Markdown ↓發佈到已配置的 GitHub 倉庫 ↓GitHub main 分支產生新提交 ↓Cloudflare Pages 檢測到提交 ↓運行 Hugo，生成 public/ ↓更新 pages.dev 和自定義域名兩個需要分別授權的平台連接Cloudflare 和落筆都需要訪問 GitHub，但它們是兩次獨立授權：Cloudflare 需要讀取 GitHub 倉庫，用於構建和部署；落筆需要向目標 GitHub 倉庫推送文章。不要把 GitHub 密碼、PAT、OAuth Token 或 Cloudflare API Token 寫進 Hugo 配置、文章、提示詞或 GitHub 倉庫。需要授權時，按頁面提示使用官方授權流程。03|二、GitHub 倉庫應該如何組織建議為博客建立一個獨立 GitHub 倉庫，例如：my-blog/├── hugo.toml├── content/│ ├── _index.md│ └── posts/│ ├── _index.md│ └── first-post/│ ├── index.md│ └── cover.png├── themes/│ └── <主題名稱>/├── layouts/├── static/├── assets/├── .gitignore└── README.md目錄用途路徑用途hugo.tomlHugo 網站名稱、域名、語言、主題和功能配置content/網站內容源文件content/posts/博客文章統一目錄content/posts//一篇文章及其圖片組成的文章包themes/Hugo 主題；主題必須能在乾淨環境中使用layouts/覆蓋主題模板的位置static/直接複製到網站根目錄的靜態文件assets/需要 Hugo 處理的樣式、腳本或資源public/Hugo 構建產物，通常不作為源碼維護文章為什麼使用文件夾每篇文章使用 Hugo 的 leaf bundle 結構：content/posts/my-first-post/├── index.md├── cover.png└── diagram.png這樣正文和圖片天然屬於同一篇文章，移動、備份和發佈時不容易丟失資源。文件夾名稱就是文章的 URL slug，例如：content/posts/my-first-post/→ https://blog.example.com/posts/my-first-post/第一次發佈後不要隨意修改 slug，否則文章地址會改變，後續更新也可能變成另一篇文章。04|三、Hugo 配置需要設置什麼hugo.toml 至少需要明確以下字段：baseURL = 'https://blog.example.com/'languageCode = 'zh-cn'title = '我的博客'theme = 'PaperMod'[params] mainSections = ['posts']字段說明字段設置規則baseURL填寫最終網站地址，替換成自己的域名，並保留結尾斜槓languageCode例如 zh-cn、en-ustitle網站名稱theme已安裝並提交到倉庫的主題名稱params.mainSections博客文章目錄，建議設置為 posts主題可以使用 PaperMod，也可以使用其他 Hugo 主題。無論選擇哪個主題，都要確保：主題代碼或模塊版本已經固定；Cloudflare 的構建環境可以取得主題；本地執行 hugo --gc --minify 可以成功；GitHub 新建 checkout 後仍然可以成功構建。05|四、文章 Front Matter 如何設置一篇標準文章的 index.md 可以這樣寫：---title: "我的第一篇文章"date: 2026-08-05draft: falsetags: - 寫作 - Hugodescription: "一段可選的文章摘要"---正文從這裏開始。字段是否必需說明title建議必需文章標題date建議必需發佈日期，使用 YYYY-MM-DDdraft建議必需false 才會進入正式構建tags可選標籤列表description可選文章自己的摘要cover主題相關主題支持封面時再配置沒有文章摘要時，直接省略 description，不要用項目介紹或默認宣傳語代替。06|五、Cloudflare Pages 如何配置1. 創建 Pages 項目在 Cloudflare 控制枱進入：Workers & Pages→ Create application→ Pages→ Connect to Git選擇 GitHub，授權 Cloudflare 訪問博客倉庫，然後選擇剛才創建的 GitHub 倉庫。2. 設置構建參數Cloudflare Pages 字段推薦值Production branchmainBuild commandhugo --gc --minifyBuild output directorypublicRoot directory/；如果是 monorepo，則填寫 Hugo 項目所在目錄HUGO_VERSION與本地驗證通過的 Hugo 版本一致Hugo 默認把網站生成到項目根目錄的 public/。Cloudflare Pages 應該發佈這個目錄，而不是 content/ 或 Hugo 源碼目錄。3. 綁定域名首次部署成功後，Cloudflare 會提供一個 pages.dev 地址。確認這個地址可以打開後，再進入：Pages 項目→ Custom domains→ Set up a domain填入自己的正式域名，例如 https://blog.example.com。如果使用子域名，需要按 Cloudflare 提示配置 CNAME；如果使用根域名，需要把域名接入對應 Cloudflare Zone。域名配置完成後，把同一個地址寫回 hugo.toml 的 baseURL。4. 驗證自動部署在 GitHub 修改一個非敏感的頁面配置並推送到 main，確認：GitHub 提交旁邊出現 Cloudflare Pages 構建狀態；Cloudflare Pages 生成新的 Production deployment；pages.dev 和自定義域名都能打開新內容。Cloudflare Pages 還可以為 Pull Request 和其他分支生成預覽地址。正式博客使用 main，測試改動可以先走預覽。07|六、把搭建過程交給 AI AgentAI Agent 的職責是：詢問缺少的配置；創建 Hugo 文件和目錄；檢查本地構建；幫用戶準備 GitHub 倉庫；引導用戶完成 Cloudflare 授權和設置；最後引導用戶在落筆中綁定博客。AI Agent 不應該：索要或保存密碼、PAT、OAuth Token；在沒有權限時聲稱已經創建 GitHub 倉庫；在沒有 Cloudflare 頁面證據時聲稱已經部署成功；擅自把用戶的文章發佈到別人的倉庫或域名；創建一套與 Cloudflare Pages 並行的服務器或 GitHub Actions 流程。08|七、可以直接複製給 AI Agent 的主提示詞將下面整段內容複製給支持終端、文件編輯或瀏覽器操作的 AI Agent。沒有這些工具時，Agent 應把命令和點擊路徑寫出來，由用戶手動執行。你是我的博客搭建嚮導和工程實施 Agent。請帶我從零搭建一套“落筆（Loby）一鍵發佈到我的博客”的完整流程。目標架構：- Hugo：生成靜態博客網站；- GitHub：保存 Hugo 源碼、文章、圖片和版本歷史；- Cloudflare Pages：連接 GitHub，在 main 分支變化後自動構建和部署；- 落筆：作為日常寫作和一鍵發佈入口。我的配置：- 博客名稱：{{BLOG_NAME}}- GitHub 用戶名或組織：{{GITHUB_OWNER}}- GitHub 倉庫名：{{GITHUB_REPO}}- 正式網站地址：{{SITE_URL}}- 網站語言：{{LANGUAGE_CODE}}- Hugo 主題：{{HUGO_THEME}}- 落筆寫作庫路徑：{{LOBY_LIBRARY_PATH}}- 本機系統：{{OPERATING_SYSTEM}}工作規則：1. 先檢查我提供的信息是否完整，只詢問缺少的必要信息。2. 如果你有終端工具，就檢查 git、hugo、gh、wrangler 是否可用；如果沒有，就給我可複製的命令。3. 如果你有文件編輯能力，就在指定目錄生成文件；如果目錄已有文件，先讀取並保護現有內容，不要直接覆蓋。4. 所有需要登錄、授權或綁定域名的操作，都必須明確告訴我需要在瀏覽器中點擊什麼；沒有真實成功結果前，不要說“已完成”。5. 絕不索要、回顯、保存或提交 GitHub 密碼、PAT、OAuth Token、Cloudflare API Token 或其他秘密。6. 不使用 GitHub Actions、服務器或第二套發佈服務，除非我明確要求。默認使用 Cloudflare Pages 的 GitHub 集成。7. 所有路徑、倉庫名、域名、標題和語言都使用我的配置，不要使用示例賬號或別人的域名。請按以下階段執行：階段 1：確認方案- 解釋 Hugo、GitHub、Cloudflare Pages 和落筆各自負責什麼。- 輸出一張簡短的數據流圖。- 列出還缺少的用戶輸入。階段 2：創建 Hugo 博客- 創建 hugo.toml。- 設置 baseURL、languageCode、title、theme 和 content/posts 文章目錄。- 創建 content/_index.md 和 content/posts/_index.md。- 創建 themes、layouts、static、assets 等必要目錄；主題必須在乾淨環境可以獲得。- 創建 .gitignore，忽略 public、Hugo 緩存、系統臨時文件和本地秘密文件。- 創建 README.md，寫清本地預覽、構建和 Loby 發佈方式。- 文章使用以下結構： content/posts/<slug>/index.md content/posts/<slug>/圖片文件- 不要創建依賴本機絕對路徑的配置。階段 3：本地驗證- 執行 hugo version。- 執行 hugo --gc --minify。- 如有問題，先修復真實錯誤，再繼續。- 告訴我 Hugo 版本、構建結果和生成目錄。階段 4：GitHub- 如果我還沒有倉庫，指導我創建 {{GITHUB_OWNER}}/{{GITHUB_REPO}}。- 將博客源碼推送到 main。- 推送前檢查 git status、遠程地址、敏感文件和構建結果。- 如果你沒有 GitHub 權限，停下來告訴我完成授權的具體步驟。- 最終報告 GitHub 倉庫地址和 main 的提交信息。階段 5：Cloudflare Pages- 指導我進入 Workers & Pages → Create application → Pages → Connect to Git。- 連接 GitHub 並選擇 {{GITHUB_OWNER}}/{{GITHUB_REPO}}。- 設置： Production branch = main Build command = hugo --gc --minify Build output directory = public Root directory = / HUGO_VERSION = 本地驗證通過的 Hugo 版本- 指導我在 Pages → Custom domains 中綁定 {{SITE_URL}}。- 說明 DNS 需要如何配置。- 等待我完成授權和域名操作，不要假裝替我完成。- 驗證 pages.dev 地址、Production deployment 和正式域名。階段 6：落筆- 指導我打開落筆“設置 → 發佈 → 發佈目標”。- 點擊“添加發布目標 → GitHub”，按頁面完成 GitHub 官方授權。- 點擊“添加 GitHub 發佈目標 → Hugo 博客”。- 指導我填寫： 目標名稱 = {{BLOG_NAME}} GitHub 倉庫 = {{GITHUB_OWNER}}/{{GITHUB_REPO}} 發佈分支 = main 文章目錄 = content/posts 網站地址 = {{SITE_URL}}- 指導我在項目設置中綁定這個發佈目標。- 不要讓我手工編輯落筆的內部配置文件或秘密存儲。階段 7：真實冒煙測試- 讓我在落筆中創建一篇短測試文章。- 使用“發佈到博客”執行一次發佈。- 檢查 GitHub 是否出現新文章文件夾和文章文件。- 檢查 Cloudflare 是否產生新的構建和 Production deployment。- 檢查最終文章 URL 是否可以打開。- 再修改同一篇文章並點擊“更新”，確認文章地址沒有變化。最終請交付：1. 博客目錄樹；2. hugo.toml 的關鍵字段說明；3. GitHub 倉庫設置；4. Cloudflare Pages 構建設置；5. 落筆需要填寫的字段；6. 本地、GitHub、Cloudflare 和文章 URL 的驗收結果；7. 一份故障排查表，至少覆蓋 Hugo 構建失敗、主題缺失、GitHub 授權失敗、Cloudflare 構建失敗、DNS 未生效、文章 draft=true 和落筆文章目錄配置錯誤。09|八、落筆中的日常發佈流程博客初始化完成後，用戶不需要再打開終端：落筆中完成文章 ↓確認標題、標籤、封面和文章狀態 ↓點擊“發佈到博客” ↓確認發佈目標 ↓等待 GitHub 和 Cloudflare 完成 ↓打開文章連結檢查更新文章時，直接在落筆中修改原文並點擊“更新”。不要在 GitHub 網頁端複製粘貼文章，也不要隨意改文章文件夾名稱。10|九、常見錯誤現象優先檢查Cloudflare 找不到文章Build output 是否為 public，文章是否在 content/postsHugo 本地能構建，Cloudflare 失敗Hugo 版本、主題依賴、主題是否已提交到 GitHub頁面能打開但連結不對hugo.toml 的 baseURL 是否仍是示例域名落筆找不到倉庫落筆 GitHub 授權是否包含目標倉庫發佈後文章沒有出現draft 是否為 true，Cloudflare 構建是否成功域名無法訪問Pages 自定義域名是否已關聯，DNS/CNAME 是否正確更新變成了新文章是否修改了文章文件夾名稱或 slug11|官方參考Cloudflare Pages Git integration: https://developers.cloudflare.com/pages/configuration/git-integration/Cloudflare Pages GitHub integration: https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/Cloudflare Pages Hugo guide: https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/Cloudflare Pages custom domains: https://developers.cloudflare.com/pages/configuration/custom-domains/Hugo page bundles: https://gohugo.io/content-management/page-bundles/Hugo quick start: https://gohugo.io/getting-started/quick-start/@麥先生說如果對你有用，歡迎點贊、分享、推薦點贊分享推薦A LIFE OF GROWTH

• 用落筆一鍵發佈博客：Hugo、GitHub 與 Cloudflare…
• 用落筆一鍵發佈博客：Hugo、GitHub 與 Cloudflare…
• 用落筆一鍵發佈博客：Hugo、GitHub 與 Cloudflare…
• 用落筆一鍵發佈博客：Hugo、GitHub 與 Cloudflare…
• 用落筆一鍵發佈博客：Hugo、GitHub 與 Cloudflare…