從零打造現代化技術部落格：Astro + Keystatic 踩坑與實戰紀錄

前言

作為一個開發者，擁有一個完全屬於自己的技術部落格是必經之路。不想受限於 Medium 的付費牆，也不想維護沉重的 WordPress，我選擇了 Jamstack 架構。

今天的目標很明確：用一天的時間，搭建一個高效能、好管理、且零成本託管的部落格。

為什麼選擇這個技術組合？

Astro：目前最適合內容網站的框架。預設輸出 0 JavaScript，速度飛快，且對 Markdown/MDX 的支援極佳。
Keystatic：這是我這次最大的發現。它是一個 “Git-based CMS”，不需要資料庫，文章內容直接存成 Repo 裡的 .mdx 檔案。這意味著「內容即代碼」，版本控制超級方便。
GitHub Pages：免費、穩定，搭配 GitHub Actions 實現自動化部署。

開發過程中的關鍵踩坑 (Key Takeaways)

雖然官方文件寫得很美好，但在實際整合時還是遇到了幾個棘手的問題。以下是今天的「戰場筆記」：

1. Tailwind CSS v4 的版本衝突

起初使用 npx astro add tailwind 時直接報錯崩潰。原因是 Tailwind v4 剛發布，但 Astro 的整合套件目前還只認得 v3。 ✅ 解法：強制安裝 v3 版本，繞過相容性問題。

npm install @astrojs/tailwind tailwindcss@^3.4

2. Keystatic 的依賴地獄 (`tslib`)

啟動 Keystatic 後台時，遇到了 Unexpected token 'N' 和 Could not resolve "tslib" 的錯誤。這是因為某些底層依賴沒有被正確拉取。 ✅ 解法：手動補齊缺失的依賴，並確保安裝了 MDX 整合。

npm install tslib
npx astro add mdx

3. 部署時的 “No Adapter” 錯誤

這是最坑的一點。Keystatic 在本地開發時需要 API 路由來運作後台，但在 GitHub Pages 這種純靜態環境下，這些動態路由會導致 Build 失敗，報錯 NoAdapterInstalled。 ✅ 解法：使用條件判斷，只在開發環境 (Development) 載入 Keystatic，生產環境則把它「踢掉」。

// astro.config.mjs
const integrations = [react(), tailwind(), mdx()];

// 關鍵：只有開發時才載入 Keystatic
if (process.env.NODE_ENV === 'development') {
  integrations.push(keystatic());
}

4. GitHub Pages 的路徑陷阱 (`BASE_URL`)

部署上線後，發現點擊文章連結會跳到 404，或者 CSS 樣式全跑掉。這是因為 GitHub Pages 的網址通常帶有 Repo 名稱（例如 /sai-blog/），但 Astro 預設是以根目錄 / 為基準。 ✅ 解法：

在 astro.config.mjs 設定正確的 base。
在程式碼中全面改用 import.meta.env.BASE_URL 來拼接連結。

// 修改前
<a href={`/posts/${slug}`}>...</a>

// 修改後
<a href={`${import.meta.env.BASE_URL}posts/${slug}`}>...</a>

成果展示：打造沉浸式閱讀體驗

解決完技術債後，我花了一些時間打磨 UI，參考了現代化的設計風格，實作了以下功能：

動態目錄 (Table of Contents)：自動抓取 H2/H3 標題生成側邊導覽。
TL;DR 摘要框：模仿技術文件的風格，在文章開頭加入重點摘要。
閱讀資訊：自動計算字數與預估閱讀時間。
深色 Hero Header：讓標題區域更具視覺張力。

結語

今天的衝刺非常充實。雖然中間經歷了幾次報錯和部署失敗，但最終看到綠色的 Build Success 和流暢的網頁體驗，一切都值得了。

這只是開始，接下來我計畫研究如何加入 Dark Mode 切換 以及 SEO 優化。

如果你對這個架構有興趣，歡迎參考我的 GitHub Repo，或是在下方留言交流！

簡單來說

前言