维护记录
完成的工作
- 主题的六个浏览器脚本改成 TypeScript,源码放
assets/ts/,tsc 编译回 assets/js/ ✅- 源码:
pt-wasm.ts / home-title.ts / page-bg.ts / particles-wasm.ts / particles.ts / search.ts,外加 globals.d.ts(wasm 导出、三个页面配置、loader 三类全局类型) themes/self/tsconfig.json:target: es2019、module: preserve、strict 全开、noEmitOnError、newLine: lf。这些文件是经典脚本不是 ES 模块,每个都是一个 IIFE,最多往全局挂一个 window.ptWasm- 构建:新增
pnpm run build:js(= tsc -p themes/self/tsconfig.json),pnpm run build 变成「先编 JS 再 hugo --minify」,CI 部署链路自动覆盖;本地 hugo server 前记得手动跑一次 build:js - 类型检查覆盖到主题:
pnpm run typecheck 现在跑两个项目(scripts/** 与 themes/self/assets/ts/**),preflight 的 ④ 一并覆盖 bin/artifacts.sh 加第 ④ 项新鲜度检查:把 assets/ts/** 重新编译到临时目录,与提交的 assets/js/*.js 逐字节比对;忘了 build:js 会直接失败。tsc 很快(约 0.3s),所以不像 CSS 那样只在 --rebuild 时做
- 行为验证:首页 hero 粒子照常初始化(2667 颗 / step 3 / 边长 2)、站内搜索返回结果并高亮、
/particles/ 的 wasm 引擎与降级脚本都能加载、待机屏保跑完组装进入 floating(68824 颗 / 2px 网格)。控制台零错误 ✅ - 产物零漂移:把新旧两版 JS 分别过 Hugo 的 minifier 后逐文件比较,差异只有
"use strict"(tsc 的 alwaysStrict 放在文件顶部)、minifier 的变量重命名、以及我刻意补的几处 || '' / || '{}' 兜底;particles.js 除 "use strict" 外逐字节相同 ✅
遇到的问题
- TS 7 不接受
module: "none" ⚠️ - 原想用 none 表达「这是经典脚本」,但 TS 7 允许的取值里没有它(报 TS6046)。改用 preserve:不做任何模块改写,误加 import 时产物会直接在浏览器报错,而不是被悄悄包成 CommonJS。 strict 会给每个产物加上顶层 "use strict" ⚠️ - alwaysStrict 是 strict 的连带项,产物第一行多了一句指令。与原先 IIFE 内的 'use strict' 语义等价,无害,没有关掉。- 预览面板里
requestAnimationFrame 不触发 ⚠️ - 实测 rafWorks: false,所以粒子页这种「只在 rAF 里画」的页面采样不到像素,动画类页面无法用像素验证。改用两条确定性证据:① 屏保走 startBuild() 的同步 tick() + blit(),能读到真实像素;② 把新旧 JS 分别构建、比较 minify 后的产物。 hugo --minify 不会渲染草稿页 ⚠️ - 第一次对比时 /particles/ 的两个脚本没进产物,因为没加 -D;两边都加 -D 后文件才对得上。
下次建议
- 源文件里的
var 是从 JS 原样保留的(这次是翻译不是重写)。若想现代化成 const / let,建议单独一次改动,并靠「minify 后逐字节比较」守住行为不变。 assets/ts/ 与 assets/js/ 都在 themes/self/ 下,所以改任何一个 .ts 都会让 CSS 指纹失配、要求重跑 build-css。这是「指纹覆盖整个主题目录」的有意取舍,但如果以后 JS 改动频繁,可以考虑把 assets/ts/** 与 assets/js/** 从 CSS 指纹里排除——代价是要单独维护一份「哪些文件影响 CSS」的清单。