typescript-v6

TypeScript 6 技能

通过精准的编译器指导和现代模块／运行时模式，构建、配置和调试 TypeScript 6+ 项目。

开始之前

此技能适用于实际的 TypeScript 6+ 项目工作：日常开发、配置、调试和升级。

指标	未使用技能	使用技能
升级调查时间	约 90 分钟	约 30 分钟
常见 tsconfig 回归问题	5+	0-1
Token 用量	高（手动比对差异）	低（依据发行说明提供指导）

此技能可避免的已知问题

1. 升级后因缺少 types 条目而导致意外的构建失败
2. 因未显式设置 rootDir 而导致输出路径意外变成 dist/src/...
3. 将已弃用的 moduleResolution node 或 baseUrl 设置带入 TS 6 迁移
4. 不清楚何时应使用 bundler 而非 nodenext
5. 将 ignoreDeprecations: "6.0" 过度用作长期修复方案，而非临时迁移辅助措施
6. 误将 --stableTypeOrdering 当作生产性能标志，而不是 TS 6→7 对比工具
7. 遗漏 Node／测试环境全局类型，因为 TS 6+ 项目通常需要显式设置 types 条目
8. 因 TS 6 对副作用导入采用更严格的检查，导致新的副作用导入错误

快速开始

步骤 1：明确指定重要选项

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "types": ["node"],
    "strict": true
  },
  "include": ["src/**/*"]
}

为何重要： TypeScript 6 的默认值和行为发生了足够多的变化，因此日常开发中显式配置现在更加重要。rootDir 和 types 是最需要明确设置的两项。

步骤 2：有意识地选择模块解析方式

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

为何重要： TypeScript 6 弃用了 moduleResolution: "node"／"node10"。打包应用通常应选择 bundler，而 Node.js 包通常应选择 nodenext。

步骤 3：仅当目标／库／运行时确实支持时，才使用 TS 6 时代的库类型定义

const escaped = RegExp.escape('(hello)');

const value = new Map<string, number>().getOrInsert('count', 0);

const tomorrow = Temporal.Now.instant().add({ hours: 24 });

为何重要： TypeScript 6 可以为尚未在所有运行时中推出的新平台 API 提供类型。请区分编译器类型已提供和运行时支持已提供。

步骤 4：更改代码前，先验证配置和解析

npx tsc --noEmit
npx tsc --showConfig
npx tsc --explainFiles

为何重要： TS 6+ 项目经常因实际生效的配置或包含的文件图与项目预期不符而失败。先验证这些内容，再进行重构。

关键规则

务必做到

• 当源文件位于 tsconfig.json 的子目录中时，显式设置 rootDir
• 当项目依赖 Node、测试运行器、Workers、Bun 或其他全局类型提供方提供的环境全局类型时，显式设置 types 数组
• 打包 Web 应用优先使用 moduleResolution: "bundler"，现代 Node.js 包优先使用 moduleResolution: "nodenext"
• 将 ignoreDeprecations: "6.0" 视为短期迁移临时方案，而非最终解决方案
• 直接使用 paths，不要依赖已弃用的 baseUrl
• 当项目确实依赖 Node、测试、Worker 或 Bun 全局类型时，显式设置 types
• 将副作用导入视为有意检查的对象，并仔细修正其路径
• 推荐 Temporal、getOrInsert 或 RegExp.escape 前，先验证运行时支持情况
• 仅在比较 TS 6 和 TS 7 的行为或调查对顺序敏感的问题时，使用 --stableTypeOrdering
• 当 TS 6+ 代码暴露出应明确处理的类型歧义时，使用 satisfies、穷尽式 never 检查和断言函数
• 配置更改后，以及类型模式重构后，都重新运行 tsc --noEmit

切勿执行

• 切勿推荐已弃用的 moduleResolution: "node" / "node10" 作为面向未来的方案
• 切勿推荐已移除的 moduleResolution: "classic" 作为回退方案
• 如果项目依赖 @types/node、测试全局类型或平台全局类型，切勿让 types 保持隐式
• 切勿假设 ignoreDeprecations: "6.0" 在 TypeScript 7 中仍能继续使用
• 切勿把 TS 7 预览版的情况说成已经是默认编译器运行时
• 切勿暗示 TypeScript 类型能保证新的 ECMAScript API 在运行时可用
• 切勿照搬仍使用 skipDefaultLibCheck、downlevelIteration 或旧版 AMD/UMD/SystemJS 示例的 TS 6 之前的 tsconfig 建议

常见错误

错误 - 依赖 TS 6 之前的环境类型加载方式：

{
  "compilerOptions": {
    "outDir": "./dist"
  }
}

正确 - 声明项目实际需要的全局类型：

{
  "compilerOptions": {
    "outDir": "./dist",
    "types": ["node"]
  }
}

原因： 在 TS 6+ 中，如果项目依赖环境全局类型，显式设置 types 可以提升性能和可预测性。

错误 - 原样保留已弃用的路径别名配置：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@app/*": ["app/*"]
    }
  }
}

正确 - 在 paths 中内联源代码前缀：

{
  "compilerOptions": {
    "paths": {
      "@app/*": ["./src/app/*"]
    }
  }
}

原因： baseUrl 在 TS 6 中已弃用。面向未来的配置应直接使用 paths 条目。

错误 - 类型扩大掩盖了实际配置约定：

const compilerMode = {
  moduleResolution: 'bundler',
  strict: true,
};

正确 - 检查字面量类型，同时避免类型扩大：

const compilerMode = {
  moduleResolution: 'bundler',
  strict: true,
} satisfies {
  moduleResolution: 'bundler' | 'nodenext';
  strict: boolean;
};

原因： satisfies 并非 TS 6 中新增的功能，但它是让配置和选项对象保持精确、又不丢失类型推断的最佳方式之一。

错误 - 联合类型处理悄悄遗漏了新情况：

type ResolutionMode = 'bundler' | 'nodenext' | 'preserve';

function describeMode(mode: ResolutionMode) {
  if (mode === 'bundler') return 'bundled app';
  return 'node-style runtime';
}

正确 - 穷尽处理联合类型：

type ResolutionMode = 'bundler' | 'nodenext' | 'preserve';

function describeMode(mode: ResolutionMode) {
  switch (mode) {
    case 'bundler':
      return 'bundled app';
    case 'nodenext':
      return 'node-style runtime';
    case 'preserve':
      return 'mixed emit strategy';
    default: {
      const exhaustive: never = mode;
      return exhaustive;
    }
  }
}

原因： TypeScript 6+ 项目通常会在配置、平台和运行时状态中使用联合类型。通过穷尽式 never 检查，可以明确发现遗漏的情况。

错误 - 将 stableTypeOrdering 当作常规构建标志使用：

tsc --stableTypeOrdering --build

正确 - 仅将其用于比较/调试：

tsc --noEmit --stableTypeOrdering

原因： 此标志用于减少 TS 6 与 TS 7 输出中的噪声。它可能会显著拖慢类型检查，不适合作为永久默认设置。

已知问题预防

问题	根本原因	解决方案
process / describe / fs 突然缺失	项目依赖环境类型自动发现，而在 TS 6 迁移工作中已不能再安全地假设这一点	添加 "types": ["node", "jest"] 等显式条目
输出移至 dist/src/...	项目依赖推断的源代码根目录行为，而 TS 6 迁移工作通常需要用显式配置替代	显式设置 rootDir，通常为 ./src
升级警告激增	旧配置中仍保留着已弃用的模块解析或输出选项	迁移到 bundler 或 nodenext；移除已弃用的选项
副作用导入突然报错	TS 6+ 项目对副作用导入的检查更加严格	修正拼写错误、添加显式文件，或有意收紧导入路径
#/ 导入无法解析	运行时或解析模式不符合 TS 6 的支持要求	使用 Node 20+ 支持，并采用 moduleResolution: "bundler" 或 "nodenext"
新的 ES API 编译通过，但运行时失败	TS lib 类型已提供，但运行时尚不支持	分别验证运行时兼容性和 polyfill 策略
类型排序变化导致差异噪声	迁移实验期间，TS 6/TS 7 的排序方式有所不同	临时使用 --stableTypeOrdering

捆绑资源

参考资料

• TS 6 专用迁移指南 → references/migration-v6-reference.md
• 默认值和配置行为 → references/defaults-migration-reference.md
• 弃用项和替代方案 → references/deprecations-reference.md
• 模块解析和 #/ 导入 → references/module-resolution-imports-reference.md
• 新的库类型和 API → references/stdlib-types-reference.md
• 验证工作流和诊断 → references/workflow-diagnostics-reference.md
• 适用于 TS 6+ 代码的类型安全模式 → references/type-patterns-reference.md
• stableTypeOrdering 和 TS 7 相关信息 → references/stable-ordering-ts7-reference.md
• 参考资料索引 → references/README.md

配置参考

打包应用的基线配置

{
  "compilerOptions": {
    "target": "es2025",
    "module": "esnext",
    "moduleResolution": "bundler",
    "lib": ["es2025", "dom"],
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["src/**/*"]
}

关键设置：

• rootDir：避免意外生成 dist/src/... 这样的嵌套目录
• types：仅在项目确实依赖 Node、测试或平台全局变量时显式添加
• moduleResolution: "bundler"：最适合 Vite、esbuild、Rollup、Webpack 风格的应用构建
• target: "es2025" / lib: ["es2025", ...]：可使用 RegExp.escape 等 TS 6 时代引入的内置类型

Node 包的基线配置

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["es2022"],
    "rootDir": "./src",
    "outDir": "./dist",
    "types": ["node"],
    "strict": true
  },
  "include": ["src/**/*"]
}

关键设置：

• nodenext：当包的运行时语义应遵循现代 Node.js ESM/CJS 规则时使用
• 显式的 .js 导入说明符和 package.json 模块设置仍然很重要；TS 6 并不会免除这项责任

项目结构

my-ts-project/
├── src/
├── dist/
├── package.json
└── tsconfig.json

**重要原因：**TS 6 鼓励使用显式、简单的项目结构。升级时的大多数问题都源于旧版配置的隐式行为，而非源代码语法。

常见模式

直接迁移 paths

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

使用此方案，而不是继续保留已弃用的 baseUrl。

使用 #/ 子路径导入包内别名

{
  "name": "my-package",
  "type": "module",
  "imports": {
    "#/*": "./dist/*"
  }
}

import * as utils from '#/utils.js';

当你的包和运行时已支持 Node 的 imports 字段，且你希望使用包原生别名，而非仅适用于打包工具的约定时，可采用此方案。确保映射与包实际发布的文件完全一致。

临时迁移屏障

{
  "compilerOptions": {
    "ignoreDeprecations": "6.0"
  }
}

仅在迁移受阻时短暂使用。请计划在 TS 7 发布前移除它。

Monorepo/项目引用检查

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "isolatedDeclarations": true,
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

当包会生成 .d.ts 文件或参与项目引用时，请使用此方案。isolatedDeclarations 并非 TS 6 独有，但很适合更严格、更显式的 TS 6+ 工作流。

验证工作流

npx tsc --noEmit
npx tsc --showConfig
npx tsc --explainFiles
npx tsc --traceResolution

各命令的适用场景：

• --noEmit：配置或类型变更后的第一轮健康检查
• --showConfig：排查虚假设置问题前，确认最终合并后的配置
• --explainFiles：了解某个文件为何属于当前程序，或文件依赖图为何发生变化
• --traceResolution：排查 paths、包导出、types 或 #/ 导入解析问题

故障排查

“Cannot find name 'process'” / “Cannot find name 'describe'”

添加适当的 types 条目，并在需要时安装匹配的 @types/* 包。

输出路径意外发生变化

显式设置 rootDir。这是 TS 6 升级中最常见的回归问题之一。

持续出现弃用选项警告

迁移并弃用相关设置；仅在替代方案尚未完成时使用 ignoreDeprecations: "6.0"。

TS 6+ 中出现新的副作用导入错误

检查导入路径，并确认该文件是否预期仅作为副作用模块。TS 6 在此处采用了更严格的检查，因此旧的拼写错误或含义模糊的副作用导入可能会暴露出来。

RegExp.escape / Temporal / getOrInsert 编译通过，但在生产环境中失败

检查运行时支持情况。TS 6 可能会先提供类型支持，但并非所有目标环境都已实现相应的运行时 API。

设置检查清单

• 如果源文件位于 tsconfig.json 所在目录的子目录中，请明确设置 rootDir
• 为 Node、测试、Workers、Bun 或其他全局声明平台明确设置 types
• 将 moduleResolution 设为 bundler 或 nodenext，而非已弃用的 node / node10
• 确保复制的配置中不再残留已移除的 classic 解析方式、skipDefaultLibCheck 和 downlevelIteration
• 移除已弃用的 baseUrl / downlevelIteration / ES5 时代的设置，或安排移除计划
• 如果升级后的行为仍令人困惑，请使用 tsc --showConfig 和 tsc --explainFiles
• ignoreDeprecations: "6.0" 是临时设置，且已纳入跟踪
• 根据实际运行时支持情况验证新的 TS 6 API
• --stableTypeOrdering 仅用于迁移对比，不用于常规构建

官方文档

• TypeScript 6.0 发行说明
• TypeScript 手册
• TSConfig 参考
• 编译器选项参考
• 如何选择编译器选项