typescript-v6

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript 6 Skill

TypeScript 6 技能指南

Build, configure, and debug TypeScript 6+ projects with precise compiler guidance and modern module/runtime patterns.

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

Before You Start

开始之前

This skill is for real TypeScript 6+ project work: daily development, configuration, debugging, and upgrades.

Metric	Without Skill	With Skill
Upgrade Investigation Time	~90 min	~30 min
Common tsconfig Regressions	5+	0-1
Token Usage	High (manual diffing)	Low (release-note-grounded guidance)

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

指标	未使用本技能	使用本技能
升级调研时间	~90分钟	~30分钟
常见tsconfig回归问题	5个以上	0-1个
令牌使用量	高（手动对比）	低（基于发布说明的精准指导）

Known Issues This Skill Prevents

本技能可预防的已知问题

Surprise build failures from missing
```
types
```
entries after upgrading
Unexpected
```
dist/src/...
```
output because
```
rootDir
```
was never explicit
Deprecated
```
moduleResolution node
```
or
```
baseUrl
```
settings surviving into a TS 6 migration
Confusion about when to use
```
bundler
```
vs
```
nodenext
```
Overusing
```
ignoreDeprecations: "6.0"
```
as a long-term fix instead of a temporary migration aid
Misunderstanding
```
--stableTypeOrdering
```
as a production performance flag instead of a TS 6→7 comparison tool
Missing Node/test globals because TS 6+ projects often need explicit
```
types
```
entries
New side-effect import errors because TS 6 applies stricter side-effect import checking

升级后因缺少
```
types
```
配置项导致意外构建失败
因未显式设置
```
rootDir
```
导致输出路径变为
```
dist/src/...
```
过时的
```
moduleResolution node
```
或
```
baseUrl
```
配置在TS 6迁移后仍被保留
对何时使用
```
bundler
```
与
```
nodenext
```
存在困惑
将
```
ignoreDeprecations: "6.0"
```
作为长期解决方案而非临时迁移辅助手段
误解
```
--stableTypeOrdering
```
为生产环境性能优化标志，而非TS 6→7版本对比工具
缺少Node/测试全局变量，因为TS 6+项目通常需要显式的
```
types
```
配置项
出现新的副作用导入错误，因为TS 6对副作用导入的检查更严格

Quick Start

快速开始

Step 1: Make the important options explicit

步骤1：显式设置重要配置项

json

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

Why this matters: TypeScript 6 changed enough defaults and behaviors that explicit configuration now matters more in everyday work.

rootDir

and

types

are two of the most important settings to keep intentional.

json

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

为什么这很重要： TypeScript 6 修改了大量默认配置和行为，因此在日常工作中显式配置变得更加重要。

rootDir

和

types

是需要明确设置的两个最重要的配置项。

Step 2: Pick module resolution deliberately

步骤2：谨慎选择模块解析方式

json

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

Why this matters: TypeScript 6 deprecates

moduleResolution: "node"

"node10"

. Bundled apps should usually choose

bundler

, while Node.js packages should usually choose

nodenext

json

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

为什么这很重要： TypeScript 6 弃用了

moduleResolution: "node"

"node10"

。打包类应用通常应选择

bundler

，而Node.js包通常应选择

nodenext

。

Step 3: Use TS 6-era library typings only when the target/lib/runtime really supports them

步骤3：仅在目标环境/lib/运行时真正支持时，使用TS 6时代的库类型

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

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

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

Why this matters: TypeScript 6 can type new platform APIs before every runtime ships them. Distinguish compiler types available from runtime support available.

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之前提供类型定义。要区分编译器可用类型与运行时支持特性。

Step 4: Verify config and resolution before changing code

步骤4：修改代码前验证配置与解析逻辑

bash

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

Why this matters: TS 6+ projects often fail because the effective config or included file graph is not what the project expects. Validate that first, then refactor.

bash

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

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

Critical Rules

关键规则

Always Do

必须执行

Make
```
rootDir
```
explicit when your sources are nested below the
```
tsconfig.json
```
Make the
```
types
```
array explicit for Node, test runners, Workers, Bun, or other global type providers when the project relies on those ambient globals
Prefer
```
moduleResolution: "bundler"
```
for bundled web apps and
```
moduleResolution: "nodenext"
```
for modern Node.js packages
Treat
```
ignoreDeprecations: "6.0"
```
as a short-term migration escape hatch, not the destination
Use
```
paths
```
directly instead of relying on deprecated
```
baseUrl
```
Make
```
types
```
explicit when the project truly depends on Node, test, Worker, or Bun globals
Treat side-effect imports as intentionally checked and fix their paths deliberately
Verify runtime support before recommending
```
Temporal
```
,
```
getOrInsert
```
, or
```
RegExp.escape
```
Use
```
--stableTypeOrdering
```
only when comparing TS 6 and TS 7 behavior or investigating ordering-sensitive issues
Use
```
satisfies
```
, exhaustive
```
never
```
checks, and assertion functions when TS 6+ code exposes type ambiguity that should be made explicit
Re-run
```
tsc --noEmit
```
after config changes and again after type-pattern refactors

当源码位于
```
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
```

Never Do

禁止执行

Never recommend deprecated
```
moduleResolution: "node"
```
/
```
"node10"
```
as the forward-looking path
Never recommend removed
```
moduleResolution: "classic"
```
as a fallback path
Never leave
```
types
```
implicit if a project depends on
```
@types/node
```
, test globals, or platform globals
Never assume
```
ignoreDeprecations: "6.0"
```
will keep working in TypeScript 7
Never present TS 7 preview context as if it were already the default compiler runtime
Never imply that TypeScript types guarantee runtime availability for new ECMAScript APIs
Never import pre-TS 6 tsconfig advice that still uses
```
skipDefaultLibCheck
```
,
```
downlevelIteration
```
, or old AMD/UMD/SystemJS examples

绝不推荐已弃用的
```
moduleResolution: "node"
```
/
```
"node10"
```
作为未来的技术路径
绝不推荐已移除的
```
moduleResolution: "classic"
```
作为 fallback 方案
如果项目依赖
```
@types/node
```
、测试全局变量或平台全局变量，绝不隐式保留
```
types
```
配置
绝不假设
```
ignoreDeprecations: "6.0"
```
在TypeScript 7中仍能生效
绝不将TS 7预览内容当作默认编译器运行时特性呈现
绝不暗示TypeScript类型可保证新ECMAScript API的运行时可用性
绝不引入仍使用
```
skipDefaultLibCheck
```
、
```
downlevelIteration
```
或旧版AMD/UMD/SystemJS示例的TS 6之前的tsconfig建议

Common Mistakes

常见错误

Wrong - relying on pre-TS 6 ambient type loading:

json

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

Correct - declare what global types the project actually needs:

json

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

Why: In TS 6+, explicit

types

improves performance and predictability when the project depends on ambient globals.

Wrong - keep deprecated path alias setup unchanged:

json

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

Correct - inline the source prefix in
paths
:

json

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

Why:

baseUrl

is deprecated in TS 6. The forward-looking setup is direct

paths

entries.

Wrong - type widening hides the real config contract:

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

Correct - keep literals checked without widening:

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

Why:

satisfies

is not new in TS 6, but it is one of the cleanest ways to make config and option objects precise without losing inference.

Wrong - union handling silently misses a new case:

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

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

Correct - exhaustive union handling:

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;
    }
  }
}

Why: TypeScript 6+ projects often rely on unions for config, platform, and runtime state. Exhaustive

never

checks make missing cases obvious.

Wrong - use
stableTypeOrdering
as a normal build flag:

bash

tsc --stableTypeOrdering --build

Correct - use it only for comparison/debugging:

bash

tsc --noEmit --stableTypeOrdering

Why: The flag exists to reduce TS 6 vs TS 7 output noise. It can meaningfully slow type-checking and is not intended as a permanent default.

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

json

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

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

json

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

原因： 在TS 6+中，当项目依赖环境全局变量时，显式的

types

配置可提升性能和可预测性。

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

json

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

正确 - 在
paths
中直接写入源路径前缀：

json

{
  "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 '打包类应用';
    case 'nodenext':
      return 'Node风格运行时';
    case 'preserve':
      return '混合输出策略';
    default: {
      const exhaustive: never = mode;
      return exhaustive;
    }
  }
}

原因： TypeScript 6+项目通常依赖联合类型处理配置、平台和运行时状态。穷尽式

never

检查可让遗漏的情况一目了然。

错误 - 将
stableTypeOrdering
作为常规构建标志：

bash

tsc --stableTypeOrdering --build

正确 - 仅用于对比/调试：

bash

tsc --noEmit --stableTypeOrdering

原因： 该标志的作用是减少TS 6与TS 7之间的输出差异。它会显著降低类型检查速度，并非用于永久默认配置。

Known Issues Prevention

已知问题预防

Issue	Root Cause	Solution
`process` / `describe` / `fs` suddenly missing	The project relied on ambient type discovery that is no longer safe to assume during TS 6 migration work	Add explicit entries like `"types": ["node", "jest"]`
Output moves to `dist/src/...`	The project relied on inferred source-root behavior that TS 6 migration work often needs to replace with explicit config	Set `rootDir` explicitly, usually `./src`
Upgrade warnings explode	Deprecated module resolution or emit-era options survived from older configs	Migrate to `bundler` or `nodenext` ; remove deprecated options
Side-effect imports suddenly error	Side-effect import checking is stricter in TS 6+ projects	Fix typos, add explicit files, or tighten import paths intentionally
`#/` imports do not resolve	Runtime or resolution mode does not match TS 6 support requirements	Use Node 20+ support with `moduleResolution: "bundler"` or `"nodenext"`
New ES APIs compile but fail at runtime	TS lib types are present, runtime support is not	Verify runtime compatibility and polyfill strategy separately
Type ordering changes create noisy diffs	TS 6/TS 7 ordering differs during migration experiments	Use `--stableTypeOrdering` temporarily

问题	根本原因	解决方案
`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库类型已存在，但运行时不支持	单独验证运行时兼容性并制定polyfill策略
类型顺序变化导致大量差异	迁移实验期间TS 6/TS 7的类型顺序不同	临时使用 `--stableTypeOrdering`

Bundled Resources

内置资源

References

参考文档

Dedicated TS 6 migration guide →
```
references/migration-v6-reference.md
```

Defaults and configuration behavior →

references/defaults-migration-reference.md

Deprecations and replacements →
```
references/deprecations-reference.md
```

Module resolution and
#/
imports →

references/module-resolution-imports-reference.md

New library types and APIs →
```
references/stdlib-types-reference.md
```

Verification workflow and diagnostics →

references/workflow-diagnostics-reference.md

Type-safe patterns for TS 6+ code →
```
references/type-patterns-reference.md
```

stableTypeOrdering
and TS 7 context →

references/stable-ordering-ts7-reference.md

Reference index →
```
references/README.md
```

专属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
```

Configuration Reference

配置参考

Bundled application baseline

打包类应用基线配置

json

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

Key settings:

```
rootDir
```
: Prevents accidental
```
dist/src/...
```
nesting
```
types
```
: Add it explicitly only when the project actually depends on Node/test/platform globals
```
moduleResolution: "bundler"
```
: Best fit for Vite/esbuild/Rollup/Webpack-style app builds
```
target: "es2025"
```
/
```
lib: ["es2025", ...]
```
: Gives access to TS 6-era built-in types such as
```
RegExp.escape
```

json

{
  "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", ...]

: 可访问TS 6时代的内置类型，如

RegExp.escape

Node package baseline

Node包基线配置

json

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

Key settings:

```
nodenext
```
: Use when the package's runtime semantics should follow modern Node.js ESM/CJS rules
Explicit
```
.js
```
import specifiers and
```
package.json
```
module settings still matter; TS 6 does not remove that responsibility

json

{
  "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
```
中的module配置仍然重要；TS 6并未免除这部分责任

Project Structure

项目结构

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

Why this matters: TS 6 rewards explicit, boring project structure. Most upgrade pain comes from old implicit config behavior, not from source code syntax.

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

为什么这很重要： TS 6更青睐显式、简洁的项目结构。大多数升级痛点来自旧的隐式配置行为，而非源码语法。

Common Patterns

常见模式

Direct

paths

migration

直接迁移至

paths

配置

json

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

Use this instead of keeping deprecated

baseUrl

around.

json

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

用此替代已弃用的

baseUrl

配置。

#/

subpath imports for package-internal aliases

使用

#/

子路径导入作为包内部别名

json

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

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

Use this when your package/runtime already supports Node's

imports

field and you want package-native aliases instead of bundler-only conventions. Keep the exact mapping aligned with the files the package actually ships.

json

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

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

当你的包/运行时已支持Node的

imports

字段，且希望使用包原生别名而非仅打包器支持的约定时使用。确保映射关系与包实际发布的文件一致。

Temporary migration shield

临时迁移屏蔽

json

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

Use this only long enough to unblock the migration. Plan to remove it before TS 7.

json

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

仅在解除迁移阻塞时使用。计划在TS 7发布前移除该配置。

Monorepo/project-reference check

单仓库/项目引用检查配置

json

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

Use this when packages emit

.d.ts

files or participate in project references.

isolatedDeclarations

is not TS 6-exclusive, but it fits the stricter, more explicit TS 6+ workflow well.

json

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

当包需要生成

.d.ts

文件或参与项目引用时使用。

isolatedDeclarations

并非TS 6专属，但它非常契合TS 6+更严格、更显式的工作流程。

Verification Workflow

验证流程

bash

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

When to use each command:

```
--noEmit
```
: First-pass health check after config or type changes
```
--showConfig
```
: Confirm the effective merged config before debugging phantom settings
```
--explainFiles
```
: Understand why a file is in the program or why a file graph changed
```
--traceResolution
```
: Debug
```
paths
```
, package exports,
```
types
```
, or
```
#/
```
import resolution

bash

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

各命令适用场景：

```
--noEmit
```
: 修改配置或类型后的首次健康检查
```
--showConfig
```
: 调试未知配置前，确认实际生效的合并配置
```
--explainFiles
```
: 了解文件为何被纳入项目或文件依赖图为何变化
```
--traceResolution
```
: 调试
```
paths
```
、包导出、
```
types
```
或
```
#/
```
导入的解析逻辑

Troubleshooting

故障排查

"Cannot find name 'process'" / "Cannot find name 'describe'"

Add the appropriate

types

entries and install the matching

@types/*

package if needed.

添加对应的

types

配置项，并根据需要安装匹配的

@types/*

包。

Output path changed unexpectedly

输出路径意外变更

Set

rootDir

explicitly. This is one of the most common TS 6 upgrade regressions.

显式设置

rootDir

。这是TS 6升级最常见的回归问题之一。

Deprecated option warnings keep appearing

已弃用选项警告持续出现

Migrate away from deprecated settings; use

ignoreDeprecations: "6.0"

only while the real replacement work is still in progress.

迁移至新的配置；仅在实际替换工作进行中时，临时使用

ignoreDeprecations: "6.0"

。

New side-effect import errors appear in TS 6+

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

Inspect the import path and whether the file is intended as a side-effect-only module. TS 6 applies stricter checking here, so old typos or vague side-effect imports can surface now.

检查导入路径以及该文件是否确实为仅副作用模块。TS 6对此的检查更严格，因此旧的拼写错误或模糊的副作用导入现在会暴露出来。

RegExp.escape

Temporal

getOrInsert

compile but fail in production

RegExp.escape

Temporal

getOrInsert

编译通过但生产环境运行失败

Check runtime support. TS 6 can expose types before every target environment implements the runtime API.

检查运行时支持情况。TS 6可能在目标环境实现该API之前就提供了类型定义。

Setup Checklist

安装检查清单

```
rootDir
```
is explicit if source files live below the
```
tsconfig.json
```
```
types
```
is explicit for Node, tests, Workers, Bun, or other ambient platforms

moduleResolution

bundler

nodenext

, not deprecated

node

node10

Removed
```
classic
```
resolution,
```
skipDefaultLibCheck
```
, and
```
downlevelIteration
```
are not lingering in copied config
Deprecated
```
baseUrl
```
/
```
downlevelIteration
```
/ ES5-era settings are removed or scheduled for removal
```
tsc --showConfig
```
and
```
tsc --explainFiles
```
were used if the upgrade behavior is still surprising
```
ignoreDeprecations: "6.0"
```
is temporary and tracked
New TS 6 APIs are validated against actual runtime support
```
--stableTypeOrdering
```
is only used for migration comparisons, not normal builds

若源码文件位于
```
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-v6

Original

Translation

TypeScript 6 Skill

TypeScript 6 技能指南

Before You Start

开始之前

Known Issues This Skill Prevents

本技能可预防的已知问题

Quick Start

快速开始

Step 1: Make the important options explicit

步骤1：显式设置重要配置项

Step 2: Pick module resolution deliberately

步骤2：谨慎选择模块解析方式

Step 3: Use TS 6-era library typings only when the target/lib/runtime really supports them

步骤3：仅在目标环境/lib/运行时真正支持时，使用TS 6时代的库类型

Step 4: Verify config and resolution before changing code

步骤4：修改代码前验证配置与解析逻辑

Critical Rules

关键规则

Always Do

必须执行

Never Do

禁止执行

Common Mistakes

常见错误

Known Issues Prevention

已知问题预防

Bundled Resources

内置资源

References

参考文档

Configuration Reference

配置参考

Bundled application baseline

打包类应用基线配置

Node package baseline

Node包基线配置

Project Structure

项目结构

Common Patterns

常见模式

Direct paths migration

直接迁移至paths配置

#/ subpath imports for package-internal aliases

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

Temporary migration shield

临时迁移屏蔽

Monorepo/project-reference check

单仓库/项目引用检查配置

Verification Workflow

验证流程

Troubleshooting

故障排查

"Cannot find name 'process'" / "Cannot find name 'describe'"

"Cannot find name 'process'" / "Cannot find name 'describe'"

Output path changed unexpectedly

输出路径意外变更

Deprecated option warnings keep appearing

已弃用选项警告持续出现

New side-effect import errors appear in TS 6+

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

RegExp.escape / Temporal / getOrInsert compile but fail in production

RegExp.escape / Temporal / getOrInsert编译通过但生产环境运行失败

Setup Checklist

安装检查清单

Official Documentation

官方文档

Direct
`paths`
migration

直接迁移至
`paths`
配置

`#/`
subpath imports for package-internal aliases

使用
`#/`
子路径导入作为包内部别名

`RegExp.escape`
/
`Temporal`
/
`getOrInsert`
compile but fail in production

`RegExp.escape`
/
`Temporal`
/
`getOrInsert`
编译通过但生产环境运行失败