維護記錄#
完成的工作#
- 將首頁從
profileMode 切換為 PaperMod 的 Regular Mode：移除 params.profileMode 配置，新增 params.homeInfoParams，保留原有站點標題與副標題展示。✅ - 新增
params.env = "production"，讓 PaperMod 在所有構建場景下都按生產環境處理（影響 robots、圖片優化等）。✅ - 新增
scripts/optimize-images.ts 圖片壓縮腳本，使用 sharp 對 PNG/JPEG/WebP/AVIF/GIF/TIFF 進行壓縮、限制最大寬度、生成 WebP 變體；並在 package.json 中加入 sharp 開發依賴。✅ - 更新
.github/workflows/deploy.yml：新增 bun install 和 Optimize images 步驟，CI 每次構建時自動為 assets/images 生成寬度不超過 1200px 的 .webp 變體，且不覆蓋原圖。✅ - 新增
scripts/rename-posts.ts：將 content/posts/ 下的文章批量重命名為 YYYYMMDD[xxxxxx].md（方括號為字面字符），其中日期取自 frontmatter date 字段，hash 是去除 frontmatter 後的 body 用 SHA-256 取前 3 字節（24 bit）後轉 base36（6 位固定長度）。配套重命名 assets/images/covers/{slug}.svg 並改寫 frontmatter cover.image；用 git mv 保留歷史，git 不可用時降級 fs.rename；支持 --dry-run / --verbose；已是新格式、缺 date、格式無效的文件自動跳過；目標名碰撞時按用戶策略「報錯停止」並列出衝突文件。✅ - 新增
scripts/__tests__/rename-posts.test.ts：30 個測試覆蓋 normalizeDate（三種日期格式 + 月日越界 + 補零）/ extractBody / computeHash6（確定性、長度、base36 字符集、對末尾空白敏感、SHA-256 已知向量防止誤改回 djb2）/ rewriteCoverImage / buildReport（7 個集成測試覆蓋有效文章、缺 date、無效 date、已是新格式、忽略 _index.md、自定義封面不重命名、封面物理缺失）/ detectCollisions。全綠（bun test 134/134 通過）。✅ - 用
git rm 刪除 5 對重複文章中用戶指定的 5 個，同步刪除對應的 5 個 cover SVG（避免 sync-covers 誤判為孤兒、且這些 SVG 本來就只服務被刪的 .md）。✅ - 執行
bun scripts/rename-posts.ts 完成 216 篇文章 + 215 個 cover SVG 的一次性重命名；git 全部以 R (rename) 跟蹤，完整保留歷史。✅ - 驗證
bun scripts/validate-posts.ts 全綠 + hugo --minify 乾淨構建（265 頁）。✅
遇到的問題#
- 用戶最初理解
YYYYMMDD{6位hash}.md 時我誤把方括號當成可選語法，按無方括號實現，後被糾正改為字面方括號 YYYYMMDD[xxxxxx].md（修正 computeHash6 輸出格式 + 測試 + 註釋）。⚠️ - 用戶指出 hash 用自寫 djb2 不專業，改用
node:crypto 的 SHA-256（前 3 字節，分佈更均勻、行業標準）。⚠️ - dry-run 時腳本在 5 對文件上報告目標名碰撞，懷疑 djb2 分佈問題。實際排查：4 種不同哈希（djb2 24bit / djb2 full 32bit / FNV-1a 24bit / xxhash32 24bit）以及 SHA-256 全部在完全相同的 5 對上碰撞 → 證實這 5 對 body 真的 100% 相同（完整 64 字符 SHA-256 也一致），屬於歷史遺留的真實重複文章，不是哈希質量問題。⚠️ 解決方案：用戶手動選保留哪個，
git rm 刪另一個，配套 cover SVG 同步刪除。 - 第一次
hugo --minify 後看到 public/ 裡仍有 2020-10-29-log-8/ 等舊 URL，懷疑 Hugo 把新文件當舊名渲染。⚠️ 實際是 hugo 沒清空 public/，舊文件殘留；rm -rf public/ resources/ && hugo --minify 後正確：URL 形如 /posts/2020031100oh3i/，Hugo slugify 自動去掉方括號。⚠️ - URL 全部變更：舊
/posts/2020-03-11-github-actions/ → 新 /posts/2020031100oh3i/。按用戶決定不添加 alias，所有舊 URL 將 404。⚠️
下次建議#
- 如需進一步自定義首頁信息卡片樣式，可通過
assets/css/extended/*.css 覆蓋 .home-info 相關樣式。 - 舊的
/posts/{slug}/ URL 已全部失效。如未來想恢復外部鏈接有效性，可寫一個小腳本掃描 git 歷史為每篇生成 aliases frontmatter。 - 部署到生產後建議用
curl -I 抽查若干新舊 URL 確認 404/200 符合預期，並提交 Google Search Console 站點地圖更新。