Cloudflare Pages 部署筆記：從零到上線

這個部落格本身就是「工具筆記」系列第一號作品。記錄從零到上線的流程，包含踩坑。

架構

Astro 靜態生成 ── build ──> dist/ ── wrangler pages deploy ──> Cloudflare Pages
                                                                   │
                                              blog.moshi.eu.cc（自訂網域, CF 代管 DNS）

選 Cloudflare Pages 的理由：免費、全球 CDN、不依賴家用主機在線、跟既有 moshi.eu.cc 網域同一帳號管理。

步驟

# 1. 建立 Astro 專案（minimal 模板）
npm create astro@latest -- --template minimal --no-git --no-install --yes

# 2. 安裝數學公式支援（量化文章需要）
npm install remark-math rehype-katex katex

# 3. 授權 wrangler（瀏覽器 OAuth，一次即可）
npx wrangler login

# 4. 建立 Pages 專案並部署
npm run build
npx wrangler pages deploy dist --project-name=blog

# 5. 綁定自訂網域
npx wrangler pages project list

踩坑紀錄

內容層 API：Astro 5 之後 content collections 改用 loader 寫法（glob loader + src/content.config.ts），舊的 src/content/**/config.ts 不再作用——碰到「collection 不存在」錯誤先查這點。
KaTeX CSS：rehype-katex 只處理轉換，CSS 要在 layout 手動 import 'katex/dist/katex.min.css'，否則公式排版跑掉。
中文 slug：文章檔名建議用英文/拼音，中文會變成難看的百分號編碼。

後續

部署腳本收進 package.json，之後寫文章只要：寫 markdown → npm run deploy。