一趟漫長的旅程：將我的網站遷移至 Hugo Blox Builder

經過過去幾周十分漫長且充滿了挫折的旅程，我終於將我的網站從舊的 Academic 主題遷移到全新的 Hugo Blox Builder 框架。這篇文章詳細記錄了整個過程、我遇到的挑戰，以及最終成功將所有變更合併到 master 分支的喜悅。

遷移的動機與過程

整個過程始於一個簡單的想法：將我網站的底層主題更新為一個更現代、更靈活且有活躍維護的解決方案。舊的 Academic 主題雖然服務多年，但已停止更新，而其繼任者 Hugo Blox Builder 提供了基於 Hugo 模組的現代化架構，是理所當然的選擇。

為了確保遷移過程不影響線上網站的穩定，我建立了一個新的 theme-upgrade-2025 分支。這是一個至關重要的決定，讓我有空間進行各種實驗和修復，而不必擔心破壞 master 分支上的生產環境。

遷移的具體步驟比預想的要複雜得多：

升級核心工具鏈： 新的 Blox 框架需要 Hugo Extended 的較新版本（v0.152.2 或更高）以及 Go 語言（v1.22+）來管理模組。第一步就是確保本地和 CI/CD 環境中的工具都已升級到符合要求的版本。
從主題到模組的轉變： 過去，我們只需在 config.toml 中設定 theme = "academic"。現在，我必須移除這一行，並修改 go.mod 文件，透過 Hugo 的模組系統來引入 Blox 的核心、Tailwind CSS 支援等不同功能的模組。這代表著一種架構上的根本轉變。
現代化 CI/CD 工作流程： 舊的 GitHub Actions 工作流程（.github/workflows/hugo.yml）還停留在依賴 R 語言和 blogdown 套件的陳舊設定。我對其進行了徹底的現代化改造，移除了 R 的依賴，改為使用 actions/setup-hugo 和 actions/setup-go 來設定環境。此外，為了處理 Tailwind CSS，我還加入了 actions/setup-node 來安裝 Node.js，並執行 npm ci 來安裝依賴。最後，我還增加了一個 npm audit fix 步驟，以自動修復已知的安全漏洞，提升網站的安全性。
最最重要的是，全程我放棄了之前在 Rstudio 環境下，使用 blogdown 編譯生成網頁的做法，而是在 VScode 下，藉助如今强大的 GitHub Copilot 全程幫助完成了搬家的全過程。雖然有時候給出的結果很令人迷惘，但大多數時候，我的震撼是多過於遺憾的。因爲如今 GitHub的人工智能生成代碼的過程真的是一鍵即可生成數百行甚至數千頁，以至於非常龐大且考慮周全的頁面。況且，AI幫我查缺補漏，修正了很多小錯誤。真的要感謝如今人工智能給我們帶來的各種便利。生活從未如此便捷。估計，將來人類真的會再懷念自己手寫代碼的時代。AI代碼，比我寫的不知道漂亮多少倍。我要跟上這個時代的潮流。否則真的會被後浪拍死在這片沙灘上了。

遭遇的挫折與學習

這個過程並非一帆風順，我遇到了幾個令人沮喪的問題，但每一個都帶來了寶貴的學習經驗：

神秘的 nil pointer 錯誤： 在建置過程中，我花費了大量時間來除錯 Hugo 報出的 nil pointer 錯誤。這類錯誤的訊息通常很模糊，但最終都追溯到模板中的小失誤，例如在新的區塊結構中呼叫了一個不存在的變數，或是舊的 HTML 檔案與新主題的渲染邏輯不相容。
意外刪除 Front Matter 的驚魂時刻： 在一次批次修改檔案的過程中，我不小心將所有文章的 Front Matter（即檔案頭部的 --- 配置區塊）給刪除了。這是一個足以讓心臟停止的時刻。幸運的是，我一直有著良好的 Git 提交習慣。透過 git restore 或 git checkout，我輕鬆地將所有文章恢復到出錯前的狀態，這也讓我深刻體會到版本控制的無價。
清理巨大的 .tools 目錄： 我偶然發現，一個體積龐大、包含完整 Go 語言可攜式安裝的 .tools 目錄，竟然被意外地提交到了 Git 倉庫中。這導致每次克隆或切換分支都極其緩慢。為了解決這個問題，我執行了一次大規模的清理，使用 git rm -r --cached .tools 將其從追蹤中移除，並更新了 .gitignore 檔案，確保它未來不會再被加入。
解決持續失敗的自動更新： 倉庫膨脹問題還引發了連鎖反應。GitHub 的 Dependabot（一個自動更新依賴的機器人）不斷嘗試為 .tools 目錄內的 Go 依賴建立更新，並因此持續失敗。這產生了大量的無用通知。在我清理掉 .tools 目錄並設定了 dependabot.yml，將其掃描範圍限制在根目錄後，這個噪音源才終於消失。

最終的合併與展望

經過多個夜晚的努力，我終於讓網站在保留所有原有功能、並增添了新框架優勢的情況下，能夠完美地建置。今天，我懷著激動的心情，將 update-theme 分支合併回了 master。

完成這次遷移，如釋重負。我的個人網站現在運行在一個更現代、更安全、也更易於維護的平台上。我期待著未來能夠更專注於創作新內容，而不必再為陳舊的底層技術而煩惱。

你如果有興趣，不妨也來用AI，幫自己建立一個現代化的個人網站。