---
url: /docs/adr/004-typescript-7-native-compiler.md
---
# 决策 004：类型检查工具链

**状态：** 已采纳。**日期：** 2026-09-11。

## 问题

项目迁移到 TypeScript 7 原生编译器后，部分依赖旧编程接口的工具不能直接使用。Astro 模板仍需要专用检查，不能仅因为普通 TypeScript 文件通过就省略模板验证。

## 决策

根目录 `bun typecheck` 先对公开站和官网执行 `astro sync`，生成当前内容集合类型，再使用项目引用图运行 TypeScript 7。新检出目录没有 `.astro`，不能依赖本地预览 / 构建留下的缓存；同步失败会停止后续类型检查，不提交生成文件或给内容条目强加宽类型。生成产品只同步自己的公开站，不保留独立官网的命令过滤器。

两个 Astro 项目的 `tsconfig.json` 都显式包含 `.astro/types.d.ts`，由它引入内容类型。生成文件存在不代表项目图已读取；仅用通配路径会漏掉隐藏目录，使内容查询失去集合约束。

`apps/web` 与 `apps/website` 为 `astro check` 单独声明 TypeScript 6 依赖别名，保留 `.astro` 模板检查；公开站 Worker 的普通 TypeScript 文件仍由根检查覆盖。同步内容类型不代替 Astro 模板检查，两者继续分别运行。

编辑器配置使用原生工具链对应扩展，不继续指向不存在的旧会话服务器。具体安装版本以锁文件和应用依赖为准。

## 备选方案与影响

全部停留旧编译器会延后迁移；删除 Astro 检查会失去模板验证；包装语言服务器会增加维护。窄范围依赖别名保持两种检查各自明确。

代价是安装两个版本，出现类型差异时需要区分 `bun typecheck` 与 `bun web:check`。待 Astro 依赖支持同一工具链后再评估移除别名，不根据发布时间自动升级。

原迁移记录中的耗时是当时本机观察，不作为当前每台机器的性能承诺。相关决策：[静态检查与格式化](./005-oxlint-oxfmt.md)。