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

Hexo 部署大小寫敏感問題完整筆記

hexo 新增文章

情境描述

在使用 Hexo 部署 GitHub Pages 的過程中，我們發現資料夾名稱在本地生成為小寫（如 mac），但在 GitHub 上會變回大寫（如 Mac）。這樣的情況會導致網址中大小寫不一致，對搜尋引擎優化（SEO）及現有的搜尋索引造成負面影響。這次異動的範圍其實超級大，尤其考量到之前已部署的頁面已經被搜尋引擎索引。

具體情境如下：

  1. 初始狀況：

    • 本地 hexo generate 正確生成小寫的資料夾名稱。
    • 在檢查 GitHub Pages 部署後，發現遠端仍然顯示為大寫的 Mac 資料夾。

  2. 嘗試直接在 GitHub 上修改：

    • 我們手動在 GitHub 上將 Mac 資料夾刪除，並嘗試推送更改，這個步驟成功更新了 GitHub 上的資料夾名稱。
    • 然而，當再次執行 hexo deploy 時，遠端又恢復為大寫的 Mac。

  3. 分析問題：

    • 為了解決這個問題，我們先嘗試了使用 rm -rf tags/Mac 來刪除大寫資料夾，再推送確認 GitHub 上資料夾被刪除。
    • 然後嘗試使用 mv 將 Mac 重命名為小寫的 mac，並確保這些變更已提交並推送。
    • 但是每次重新執行 hexo generate 後，Hexo 依然生成了大寫的 Mac 資料夾。
    • 最後，經分析認為可能是 Hexo 部署使用 .deploy_git 資料夾來管理緩存，這可能導致遠端在部署時帶回了之前的大小寫配置。
    • 同時，Git 對於純大小寫變更無法敏感追蹤，因此可能需要手動強制 Git 認識這些大小寫的變更。

SEO 和搜尋引擎索引的影響

需要特別注意的是，這樣的網址大小寫異動可能會對搜尋引擎造成以下負面影響：

  • 搜尋不到已發佈內容：因為原本的 URL 已被索引，如果網址的大小寫異動或結構變動，搜尋引擎可能會無法正確找到頁面。
  • 現有索引失效：搜尋引擎已經索引過的 URL（如 tags/Mac）會因為大小寫變更導致無法正確對應，進而影響網站的搜尋排名和流量。
  • 網站權重受影響：若多次更改網址結構或出現 404 錯誤，會讓搜尋引擎認為網站不穩定，可能導致網站權重降低。

這些問題的影響可能會持續一段時間，直到搜尋引擎重新索引新的 URL。因此，處理這個大小寫問題非常重要，尤其對於長期的網站流量及 SEO 成效。

問題分析

  • Git 對大小寫變更的敏感度較低，在某些系統中（如 macOS）無法正確追蹤到大小寫差異。
  • .deploy_git 資料夾緩存了之前的部署狀態，Hexo 使用它來維持部署記錄，導致每次 Hexo 部署時恢復為舊的大小寫配置。

解決方案

步驟 1：確認 _config.yml 配置

首先，檢查 Hexo 的 _config.yml 配置，特別是 permalink 的設定，確保不會影響資料夾的大小寫。

1
2
3
4
permalink: :category/:year:month:day/:abbrlink/
pretty_urls:
    trailing_index: true
    trailing_html: true

步驟 2：使用 mv 強制變更大小寫

為了讓 Git 能夠正確追蹤大小寫變更，採用以下方法強制改變資料夾名稱：

1
2
3
4
5
6
7
8
9
10
11
# 將資料夾臨時重命名為其他名稱
mv tags/Mac tags/mac_temp
git add tags/mac_temp
git commit -m "Temporarily rename Mac to mac_temp"
git push origin main

# 再將資料夾名稱更改回小寫的 `mac`
mv tags/mac_temp tags/mac
git add tags/mac
git commit -m "Rename mac_temp back to mac"
git push origin main

這時候 push 後會發現 github 上面確實 tags/Mac 這些不如預期的網址不見了，但是當我們在做一次 hexo clean && hexo generate && hexo deploy 以後會發現現在的 github 這邊之前被我們刪掉的 tags/Mac 又跑出來了。
代表問題可能不是 github cache 或者 mac 上的 git 對於大小寫不敏感造成的問題，那跟部署相關的檔案剩下 .deploy_git 了，所以才會有嘗試把 .deploy_git 刪掉重建的選項。

步驟 3：清空 .deploy_git 資料夾

刪除 .deploy_git 資料夾，以防止 Hexo 使用緩存的部署狀態。這樣可以確保下次部署時會重新生成所有文件。

1
rm -rf .deploy_git

步驟 4：重新生成並部署

執行以下命令來清理、生成、並重新部署 Hexo 靜態網站，以確保所有檔案已更新為小寫名稱。

1
2
3
hexo clean
hexo generate
hexo deploy

步驟 5：檢查 GitHub 上的資料夾名稱

完成部署後，前往 GitHub Repo，確認 tags 資料夾中小寫名稱（如 mac）已正確應用。

備選方案

若上述步驟無法解決問題，可考慮以下備選方案：

  • 使用 GitHub Actions 部署：透過 GitHub Actions 來自動化部署流程，避免 .deploy_git 緩存問題的影響，並確保每次部署時自動清除舊的部署記錄。
  • 手動刪除遠端大寫資料夾：若大寫資料夾持續出現，可以在 [your account].github.io 的 main 分支中手動刪除並推送，確保重新部署時不會出現舊資料夾。
blog
#hexo #seo
[hexo] Hexo 部署大小寫敏感問題排查與解決指南
https://terryyaowork.github.io/blog/20241029/3996696377/
作者
Terry Yao
發布於
2024年10月29日
許可協議