项目后期引入严格 TypeScript 揪出的典型隐藏缺陷与重构实录

核心结论

kimura512.dev 最初基于纯 JavaScript 构建，后续逐步重构迁移至严格 TypeScript 体系。后期引入类型系统带来的核心红利，并非凭空产生新功能，而是“彻底揪出那些深藏在运行时之下的隐性侥幸假设”。在类型检查未完全转绿之前，我暂停了所有生产部署，并将纯类型修复与功能迭代严格拆分为独立提交。

1. 拦截静默的多语言字典缺漏

多语言界面文案集中维护，但在过去，缺失特定语言词条时往往到运行时才被发现。遗漏的翻译只会静默渲染为空白或回退乱码，根本不会抛出异常。通过重构为 Record<Language, string> 强约束，缺少翻译项的文件在构建阶段便会被直接拦截。

2. 补齐 Markdown 链接的可空性防御

在解析博客正文链接时，以往代码默认假定链接地址必然存在。而在语法树中，部分标签的 href 实属可选。未加校验的字符串操作在遇到异常链接时极易崩溃。引入明确的联合类型后，迫使系统在边界处对空链接做出了妥善的容错处理。

3. 强制收敛 ISO 日期格式一致性

部分早期文章数据的日期格式存在偏差，在某些特定浏览器语言环境下解析出会显示为 Invalid Date。通过在文章数据接口上声明标准规范，任何格式有偏的数据都会在本地编译阶段被准确定位。

4. 严禁以 'as' 断言掩盖外部数据风险

后端 API 过去存在滥用 as 强行断言外部响应的现象，当第三方返回异常数据结构时依然能够蒙混过关。在网络边界处推行结构验证后，格式不符的请求将立刻被拦截在第一道防线。

5. 应对现代框架的引用生命周期

在升级现代前端框架过程中，部分组件因未显式初始化 useRef 而需要处理空指针联合判断。全面补齐 ReactNode 约束杜绝了属性传递中的潜在隐患。

6. 将编译构建作为最后防线

由于生产构建步骤会执行完整的全量类型扫描，每次推送前强制本地跑通构建，成为了个人项目抵御回归缺陷最稳固的防火墙。

7. 严格约束组件属性变体

将核心卡片组件的样式变体定义为字面量联合类型后，任何失效或拼错的变体传参都无法通过编译，从根本上杜绝了视觉样式的漂移。

8. 保持重构提交的高度纯粹

修复类型问题的代码提交与业务逻辑变更严格解耦，确保每一次改动的意图与影响范围都清晰透明。

总结

先从数据流入的核心边界筑牢类型防线，系统的整体稳定性便能以极小的改动成本实现跨越式提升。

常见问题

Q. 是否一开始就开启了最高严格级别？
并非一步到位，而是遵循循序渐进的原则，按周逐步开启各项检查规则。

Q. 代码中是否完全根绝了 any？
除极少数外部第三方 SDK 边界封装使用 unknown 过渡外，内部业务代码已实现类型全覆盖。