Hugo + GitHub Pages 建站踩坑紀錄

Sun, 06 Apr 2025 00:00:00 +0000

前言

建這個站的過程其實沒有想像中順利。這篇記錄我遇到的坑，希望能幫其他人省點時間。

坑 1：Hugo 版本不對

問題

用 apt install hugo 裝的版本太舊（0.68），很多新 theme 需要 0.110+。

解法

直接從 GitHub Release 下載 extended 版：

1
2


wget https://github.com/gohugoio/hugo/releases/download/v0.147.0/hugo_extended_0.147.0_linux-amd64.deb
sudo dpkg -i hugo_extended_0.147.0_linux-amd64.deb

一定要用 extended 版，不然 SCSS 編譯會失敗。

坑 2：GitHub Actions 的 submodule

問題

Theme 是用 git submodule add 加的，但 GitHub Actions checkout 時預設不會 clone submodule，導致 build 時找不到 theme。

解法

actions/checkout 加上 submodules: recursive：

1
2
3
4


- uses: actions/checkout@v4
 with:
 submodules: recursive
 fetch-depth: 0

坑 3：GitHub Pages Source 設定

問題

Push 上去後 GitHub Pages 顯示 404。

解法

到 repo Settings → Pages → Build and deployment → Source，選 GitHub Actions（不是 Deploy from a branch）。

很多教學文寫的是舊版用法（gh-pages branch），現在推薦用 GitHub Actions。

坑 4：baseURL 結尾斜線

問題

baseURL 沒加結尾 /，導致部分資源路徑錯誤。

解法

1
2
3
4
5


# ✅ 正確
baseURL: https://justmaker.github.io/

# ❌ 錯誤
baseURL: https://justmaker.github.io

坑 5：中文檔名和 URL

問題

中文標題預設會變成中文 URL（/post/我的文章/），在某些環境下會出問題。

解法

每篇文章都明確指定 slug：

1
2
3
4


---
title: "我的中文標題"
slug: my-english-slug
---

坑 6：搜尋功能不 work

問題

Stack theme 的搜尋功能一直轉圈。

解法

需要在 hugo.yaml 的 outputs 加上 JSON：

1
2
3
4
5


outputs:
 home:
 - HTML
 - RSS
 - JSON  # ← 搜尋功能需要這個

Stack theme 的搜尋是 client-side，靠 index.json 做全文搜尋。

總結

大部分坑都是設定問題，知道就很簡單，不知道要 debug 很久。希望這篇能幫到你。

如果你也遇到其他坑，歡迎在下方留言分享 👇

為什麼我要建這個知識庫

Tue, 01 Apr 2025 00:00:00 +0000

動機

工作幾年下來，技術筆記散落在各處——Confluence 頁面、Discord thread、各種 markdown 檔案、甚至腦子裡。每次要找之前踩過的坑，得翻半天。

是時候把這些東西整理成一個對外的知識庫了。

為什麼選 Hugo + GitHub Pages？

考慮過幾個方案：

方案	優點	缺點
WordPress	功能完整、外掛多	需要主機、慢、維護成本高
Notion	寫起來舒服	SEO 差、客製化有限
Hexo	靜態、Markdown	Node.js 生態，build 慢
Hugo	極快 build、Go 寫的、生態成熟	模板語法學習曲線

最終選了 Hugo + GitHub Pages：

免費託管，不用管主機
Markdown 寫作，工程師友善
Build 速度極快，幾百篇文章也是秒 build
搭配 AI agent 可以批量產出內容
Git 版本控制，每篇文章的修改歷史一清二楚

內容規劃

這個站會涵蓋我的主要興趣和工作領域：

🖥️ 虛擬化技術

KVM、QEMU——這是我的主戰場。從架構設計到效能調校，踩過的坑多到可以寫一本書。

🤖 AI 開發工具

OpenClaw、Claude、Copilot 的使用心得和實戰經驗。AI 輔助開發已經是我日常工作流的一部分。

⚫ 圍棋

業餘愛好，偶爾記錄覆盤心得和學習筆記。

🎹 鋼琴

練琴心得和曲目紀錄。

🏓 桌球

業餘打球的紀錄和技術筆記。

技術架構

Hugo (靜態網站產生器)
+ Stack theme (UI)
+ GitHub Pages (託管)
+ GitHub Actions (自動部署)
+ Giscus (留言系統)
+ OpenClaw (AI 輔助寫文)

整個流程：寫 Markdown → push 到 GitHub → Actions 自動 build → 部署到 GitHub Pages。

接下來

先把幾篇核心文章寫出來，建立內容基底。然後慢慢養成定期發文的習慣。

目標是每週 1-2 篇，有 AI 幫忙應該不難。

敬請期待 🚀

Github-Pages on Justmaker's KB