兩年前山姆鍋把部落格從 Hexo 換成 Astro，當時選的是 AstroPaper ⎘ 主題，之後幾乎沒大動過。今天終於坐下來把整套技術棧補上進度，順便讓站台看起來比較像「我是山姆鍋」，而不是還掛著主題預設皮膚。
這不是一篇逐步操作手冊，比較像當天做完後的回顧：改了什麼、為什麼要改、踩到哪些坑。
目錄
Astro：Content Layer 再到 7
第一步是先把站台推到 Astro 5 的 Content Layer ⎘。內容設定從舊的 src/content/config.ts 遷到專案根層的 src/content.config.ts，文章改用 glob loader 載入。連帶幾篇舊文裡不合法的 Shiki 語言標記、壞掉的圖片路徑，也一併清掉，否則新的建置管線會直接炸掉。
接著再升到 Astro 7。這段比較瑣碎，但影響面不小：
- markdown 的 remark／rehype 改走新的 unified 處理器設定
- 動態路由的
params必須明確轉成字串 - 官方 Tailwind integration 已經不建議繼續用，先暫時改成 PostCSS 過渡
CI 也順便升到 Node 24，跟本機開發環境對齊。
Tailwind CSS v4
Astro 升完後，樣式層接著上 Tailwind v4。最大的感覺是「設定檔變少了」：刪掉 tailwind.config.cjs，改用 Vite 外掛，主題 token 直接寫進 CSS 的 @theme。
Astro 元件裡的 scoped style 若要再用 @apply，還得補上 @reference，不然建置會抱怨找不到 utility。另外 v4 對 outline 的預設行為變了，站內連結的 focus ring 一度變得很突兀，後來才調回「只在鍵盤 focus 時顯示」的舊習慣。
升級過程中 header 的 flex 排版也跑掉過一次，這類細節通常要開著瀏覽器邊對才找得到。
自訂 ink-teal 品牌色
AstroPaper 預設是偏藍的強調色，暗色模式甚至帶橘。用久了總覺得不像這個站。今天把 skin token 改成墨綠色系（ink-teal）：
- 亮色強調色約等同 Tailwind
teal-700 - 暗色強調色改成較亮的 teal，對比比較舒服
- 正文改用 Noto Sans TC；程式碼區塊才走 IBM Plex Mono
- 拿掉 Flowbite，站台皮膚改成自己維護
作者卡片、提示區塊、頁首頁尾也跟著微調。目標很單純：關掉瀏覽器分頁再開，還認得出這是山姆鍋的站。
OG 圖檔重畫
社群分享預覽圖原本還是 AstroPaper 那套巢狀卡片加 inline base64 素材。品牌色一換，那些圖就顯得格格不入。
這次把 post／site 兩套模板重寫成標題優先的版面：左側色帶、淡淡的氛圍圓形、共用的主題色與字級規則。產生邏輯也抽到共用模組，之後要再改色比較不用到處找。
TypeScript 6 與工具鏈整理
最後一波是依賴體檢：TypeScript 升到 6，一併刷新過時套件。過程中順手做了幾件衛生工作：
- ESLint 改成 flat config（
eslint.config.mjs），舊的.eslintrc.js／.eslintignore退休 tsconfig拿掉已棄用的baseUrl，改靠paths- 搜尋元件、archive 動態路由、OG 產生器裡被新工具鏈抓出來的型別問題修掉
建置與 lint 能過，才比較敢說這次升級不是「本機碰巧可以跑」。
小結
一天之內把 Astro 5／7、Tailwind 4、品牌色、OG 模板與 TypeScript 6 都推過一遍，強度有點高，但大部分時間其實花在「讓舊內容與舊假設跟新 API 對上」。靜態部落格的好處是：升級痛苦是一次付清，之後寫文章還是 Markdown 開檔就好。
下一篇大概會繼續寫文章，而不是再對建置設定开战。至少，暫時是這麼計畫的。
