TypeScript 类型和构建问题
🧩 记录类型推断、声明合并、模块解析以及开发与构建环境不一致的问题。
常见症状
- IDE 无报错但 CI 构建失败，或反之
- 升级依赖后出现大量类型冲突
- 路径别名开发可用、构建或测试不可用
- 第三方包提示缺少声明文件
- 同一类型因不同依赖副本而无法赋值
排查顺序
- 确认 Node、TypeScript、包管理器版本
- 对比 IDE 使用的 TS 版本与项目版本
- 检查生效的
tsconfig：tsc --showConfig - 检查模块解析：
tsc --traceResolution - 查看重复依赖：
pnpm why/npm ls - 清理构建缓存与 lockfile 影响后复测
高频根因
include/exclude或 project references 配置错误moduleResolution与打包器模式不匹配- ESM / CJS 混用及
exports条件差异 paths只影响类型解析，运行时未配置同名别名@types主版本与运行库不兼容- monorepo 中存在多个 TypeScript 或类型包副本
修复原则
- 优先修正类型源头，不用大范围
any掩盖 - 将临时断言限制在最小边界，并注明原因
- 统一本地、CI 与编辑器的运行版本
- 对路径别名同步配置构建器、测试器和运行环境
证据清单
- 完整错误信息与首个错误位置
- Node、TS、包管理器版本
- 最终生效的 tsconfig
- 依赖树与 lockfile 变化
- 本地和 CI 的执行命令
回归验证
-
typecheck、测试和生产构建均通过 - 干净安装后可复现通过
- IDE 类型提示与 CLI 一致
- 未引入新的
any或忽略注释