工程实践与协作
当 TypeScript 走出“语法学习”阶段，团队需要关注项目结构、构建速度、跨端协作与运行时安全。本章整理在真实项目中高频出现的实践范式。
打开严格模式与增量迁移
- 新项目建议直接开启
"strict": true，再根据需要增量放开（如noPropertyAccessFromIndexSignature）。 - 旧项目迁移时，可先启用
"skipLibCheck": true、"noImplicitAny": true，逐步清理any。 - 将
tsconfig.base.json存放公共配置，各子包通过extends共享，避免重复选项漂移。
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "dist",
"types": ["vitest"]
},
"include": ["src"]
}
json
类型与运行时的边界
编译期的类型检查无法阻止运行时的无效输入，推荐配合以下方案：
- API / 表单层使用
zod、yup、valibot或自研 schema 校验。 - 后端返回值通过
io-ts、runtypes等进行 runtime validation，保持与 TS 类型同步。 - 对外透出的
fetcher/request可以返回[data, error]元组，让业务层显式处理异常。
const CreateUser = z.object({
name: z.string().min(1),
email: z.string().email(),
});
type CreateUserInput = z.infer<typeof CreateUser>;
ts
模块划分与路径别名
- 使用
paths+baseUrl统一导入路径，避免不同目录间的相对路径地狱：
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/components/*": ["src/components/*"],
"@/types": ["src/types/index.ts"]
}
}
json
- 构建工具需要同步配置（Vite
resolve.alias、Webpackresolve.alias、ts-nodetsconfig-paths）。 - 公用类型拆分至
types/或@org/types包，避免循环依赖。
依赖类型声明策略
- 优先选择自带类型的库（
"types"字段或捆绑.d.ts）。 - 对于只在开发期使用的类型声明（如
@types/jest），放在devDependencies，并在tsconfig.json的types中显式列出。 - 如果第三方缺少定义：
- 在项目内创建
types/vendor/xxx.d.ts。 - 或向 DefinitelyTyped 提 PR，长期维护。
- 在项目内创建
性能优化：增量编译与独立类型检查
- 使用
tsc --build+composite组合拆分大型仓库的构建图。 - 在 CI 中将类型检查与打包拆分（如
pnpm tsc --noEmit，辅以vue-tsc/ngc）。 - 前端框架配合语言服务：React 使用
tsc --watch搭配vite --force，Nuxt/Next 则交由框架脚手架内置的类型守护进程。
与测试、Lint 集成
- ESLint：采用
@typescript-eslint/parser，禁用 TSLint；通过eslint --ext .ts,.tsx覆盖 TS 文件。 - 单元测试：Vitest/Jest 需要在
globals.d.ts中扩展类型；端到端测试（Playwright/Cypress）建议分离独立 tsconfig，避免污染主项目配置。 - 使用
tsd,expect-type,vitest的expectTypeOf编写类型测试，确保复杂类型升级后仍保持预期推断。
团队协作清单
- 代码评审关注
any、unknown、never的使用是否合理，避免类型“漏网”。 - 构建“类型约定”文档：例如 API 接口统一通过
*.dto.ts+zod导出，组件 Props 使用type而非interface。 - 借助
changesets或release-please自动生成发布说明，携带类型变化的破坏性提示。
进一步的工程化工具
ts-node-dev/tsx：在 Node 服务端实现快速热重载。ts-morph：用于分析或批量重写 TypeScript AST。babel-plugin-parameter-decorator等工具可在 Stage-3 装饰器之外补齐生态差距（谨慎使用）。typesync、npm-check-updates：保持@types与主包版本同步。
通过这些策略，可以让 TypeScript 在中大型团队中既保持类型安全，又不影响开发节奏。下一步可以结合项目需求挑选适合的规范与自动化流程。
↑