维护记录

完成的工作

  • 将 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__（目录）或显式列举文件。