[hexo] Hexo 部署大小寫敏感問題排查與解決指南

Hexo 大小寫之謎：為什麼 tags/Mac 怎麼都改不成 tags/mac

這個 bug 讓我 debug 了整整一個下午。本地 hexo generate 明明產生的是小寫 mac，部署到 GitHub 就變回大寫 Mac。改了又改，推了又推，它就是不聽話。

先講結論

元凶是 .deploy_git 資料夾。Hexo 用這個資料夾快取部署狀態，裡面殘留著舊的大小寫設定。刪掉 .deploy_git，重新 hexo clean && hexo g -d，問題就解決了。

我是怎麼掉進這個坑的

事情是這樣的：我把 _config.yml 裡的 category_map 和 tag_map 改成全小寫，hexo generate 也確認產生了小寫的資料夾。部署上去，上 GitHub 一看——tags/Mac 還在那裡嘲笑我。

第一次嘗試：手動改 GitHub

直接到 GitHub 刪掉 tags/Mac，push。看起來成功了。然後再跑一次 hexo deploy——tags/Mac 又回來了。彷彿有某種超自然力量在保護它。

第二次嘗試：Git mv 大法

mv tags/Mac tags/mac_temp
git add . && git commit -m "temp rename" && git push
 
mv tags/mac_temp tags/mac
git add . && git commit -m "rename to lowercase" && git push

GitHub 上確實改成小寫了。開心了三秒鐘。然後 hexo clean && hexo g -d——tags/Mac 又！回！來！了！

真相大白

到這裡我終於意識到，問題不在 Git 的大小寫敏感度（雖然 macOS 的 Git 預設確實不敏感），也不在 GitHub 的 cache。問題在 Hexo 的 .deploy_git 資料夾。

這個資料夾是 hexo-deployer-git 用來維持部署歷史的。它裡面完整保留了上次部署的所有檔案——包括大寫的 Mac。每次 hexo deploy，它會拿這個資料夾跟新產生的檔案做 diff 然後推送。但 Git 認為 Mac 和 mac 是同一個東西，所以 diff 裡不會出現這個變更。

解法：砍掉重練

rm -rf .deploy_git
hexo clean
hexo generate
hexo deploy

刪掉 .deploy_git 後，hexo deploy 會從零開始建立部署記錄，這次就不會有舊的大寫殘留了。

為什麼這件事很重要？

不只是強迫症的問題。URL 的大小寫變更會直接衝擊 SEO：

• 搜尋引擎已經收錄的 tags/Mac 會 404
• 多次變更 URL 會讓搜尋引擎覺得你的網站不穩定，降低權重
• 如果有人分享過舊連結，全部都會壞掉

所以如果你一開始就沒注意到這個問題，等到發現的時候影響範圍可能已經很大了。

預防措施

如果你也遇到類似的問題，或者想從一開始就避免：

1. 在 _config.yml 設定好 category_map 和 tag_map，統一用小寫英文
2. 如果發現部署後大小寫不對，直接刪 .deploy_git 重新部署
3. 考慮改用 GitHub Actions 部署，每次都是全新 build，不存在 cache 問題

---

Debug 了一個下午，最後解法就是 rm -rf。程式設計師的日常不就是這樣嗎。