維護記錄

完成的工作

  • 將 scripts/rename-posts.ts 接入 .github/workflows/deploy.yml：在 Install Bun dependencies 之後、Generate covers and inject front matter 之前新增 Rename posts 步驟，使每次 master 推送自動將文章重命名為 YYYYMMDD[xxxxxx].md，並同步處理 cover SVG 與 frontmatter 引用。✅
  • package.json 新增 typescript@7.0.2 與 @types/bun 開發依賴，用於 CI 中編譯腳本。✅
  • 新增 tsconfig.scripts.json：將 scripts/**/*.ts 編譯輸出到 scripts/dist/，noEmitOnError: false 保證即使存在類型錯誤也會產出 JS。✅
  • .gitignore 增加 scripts/dist/，避免提交 CI 產物。✅
  • 更新 .github/workflows/deploy.yml：安裝依賴後先執行 bunx tsc -p tsconfig.scripts.json，隨後所有 bun scripts/*.ts 改為 bun scripts/dist/*.js。✅
  • 修復 scripts/format-markdown.ts 中 execSync 的 shell: true 在 TypeScript 7 / @types/node 下產生的類型錯誤，改為根據平臺選擇 cmd.exe 或 /bin/sh。✅
  • 修復 scripts/__tests__/rename-posts.test.ts 的跨文件 mock.module 汙染問題：在 beforeEach 中恢復真實 node:fs/promises 與 node:fs 模塊，避免其它測試的 mock 影響真實 fs 集成測試。✅
  • 遷移到 Node v24：
    • package.json 刪除 bun-types、@types/bun，新增 @types/node@^24；移除 bun.lock，由 npm install 生成 package-lock.json。
    • tsconfig.scripts.json 切換到 module/moduleResolution: NodeNext，使編譯產物的相對導入帶上 .js 後綴。
    • 所有腳本的 shebang 和使用說明改為 node scripts/dist/<name>.js；scripts/rename-posts.ts 的 Bun.spawn 替換為 node:child_process 的 spawn。
    • 所有 8 個測試文件改用 node:test + 本地 expect 助手（scripts/__tests__/expect.ts），並把原本 mock node:fs/promises 的用例改為真實臨時目錄集成測試（inTempDir 助手），避免了 Node 實驗性 --experimental-test-module-mocks 的緩存痛點。
    • 5 個 GitHub Actions workflow（deploy.yml、test-scripts.yml、check-dead-links.yml、sync-covers.yml、validate-posts.yml）移除 oven-sh/setup-bun，改為 actions/setup-node@v4 + npm install + npx tsc + node scripts/dist/*.js。✅

遇到的問題

  • tsc 首次編譯報錯 Cannot find type definition file for 'bun'，原因是僅安裝 bun-types 時 types: ["bun"] 無法解析；補充安裝 @types/bun 後解決。⚠️
  • 編譯過程中 scripts/format-markdown.ts 的 shell: true 觸發類型錯誤，已按平臺顯式指定 shell 路徑。⚠️
  • 全量 bun test 因 mock.module 在 bun:test 中跨文件持久而偶發/必發失敗；已通過恢復真實模塊解決。⚠️
  • Node 原生 ESM 不支持擴展名省略，源 TS 文件全部相對導入加上 .js 後綴。⚠️
  • Node 的 mock.module 只能影響後續 import()，而 ESM 模塊緩存對同一次 import 複用舊導出；改用真實臨時目錄集成測試以繞過實驗性 API。⚠️
  • node --test scripts/dist/__tests__/*.js 在 npm scripts 中依賴 shell 展開 glob，CI (bash) 正常；Windows 上需另行處理。⚠️

下次建議

  • 觀察首次遷移後 CI 運行日誌（Hugo on GitHub Pages、Test Scripts 等），確認 Node 工具鏈無迴歸。
  • 如需把 npm test 在 Windows 上做成跨平臺，可改用 node --test scripts/dist/__tests__（目錄）或顯式列舉文件。