JavaScript / TypeScript / 知识点
TypeScript 速查手册
手册条目
创建 TypeScript 项目并生成基础配置文件。
初始化 TypeScript 项目
用于从空目录创建可复现的 TypeScript 项目:将编译器安装为开发依赖,生成 package.json、锁文件和 tsconfig.json,再执行一次类型检查。优先使用项目内的 tsc,避免全局版本与锁定版本不一致。
快速初始化
以下命令适用于 macOS、Linux 或 Git Bash,并要求 ts-demo 目录尚不存在。set -e 会在任一步失败时停止。
set -e
mkdir ts-demo
cd ts-demo
npm init -y >/dev/null
# 安装到项目中,由 package-lock.json 记录实际版本。
npm install --save-dev typescript --silent --no-audit --no-fund
npx tsc --init >/dev/null
mkdir src
cat > src/index.ts <<'TS'
const message: string = "TypeScript ready";
console.log(message);
TS
test -f tsconfig.json && echo "tsconfig.json created"
# 只检查类型,不生成 JavaScript。
npx tsc --noEmit && echo "type-check passed"
npx tsc --version预期输出
tsconfig.json created
type-check passed
Version <VERSION><VERSION> 是本地安装的实际版本。三行均出现,表示配置文件已生成、源码通过检查,并且 npx 调用的是项目编译器。
生成文件
| 路径 | 作用 |
|---|---|
package.json |
记录依赖和脚本 |
package-lock.json |
锁定依赖解析结果,通常应提交 |
tsconfig.json |
控制输入文件、检查规则和输出 |
src/index.ts |
最小 TypeScript 源码 |
node_modules 不应提交;通常还会在 .gitignore 中加入 dist/。是否忽略其他缓存目录,应按项目构建工具决定。
常用命令
| 命令 | 用途 |
|---|---|
npx tsc --noEmit |
仅做类型检查 |
npx tsc |
按最近的 tsconfig.json 编译 |
npx tsc --watch |
持续监听并重新检查 |
npx tsc -p <PATH> |
使用指定配置文件 |
风险与排障
在非空目录执行初始化,可能改写现有 package.json 或同名源码。触发条件是目录已存在项目文件;后果是依赖、脚本或代码被覆盖。安全做法是先检查 git status,或始终在新目录中执行。
不要使用全局 tsc 验证项目。全局版本漂移会造成选项、默认值和诊断结果不同;统一运行 npx tsc,并用 npm ls typescript --depth=0 核对本地依赖。
执行 npx tsc src/index.ts 时,显式文件参数会绕过常规项目配置。验证完整项目应使用 npx tsc --noEmit;指定其他配置时使用 npx tsc -p <PATH>。
若安装中断或提示找不到 tsc,先确认 node --version 与 npm --version 可执行,再运行 npm install 恢复依赖。不要随意删除锁文件,否则可能引入整棵依赖树的版本变化。
设置 TypeScript 编译选项和项目行为。
配置 tsconfig.json
tsconfig.json 决定编译范围、类型检查强度、模块规则和输出目录。下面是一份适用于 Node.js 20+ 应用的严格配置;浏览器打包项目或旧版 Node.js 需要调整模块选项。
推荐配置
此配置要求 TypeScript 5.9+,并需要安装 @types/node。显式设置 rootDir 与 outDir,可固定源码到产物的目录映射。
{
"compilerOptions": {
"target": "ES2023",
"lib": ["ES2023"],
"module": "node20",
"types": ["node"],
"rootDir": "./src",
"outDir": "./dist",
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"noEmitOnError": true,
"sourceMap": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"skipLibCheck": true
},
"include": ["src/**/*.ts"],
"exclude": ["dist", "node_modules"]
}module: "node20" 按 Node.js 20 的模块规则检查和生成代码。普通 .ts 文件最终按 ESM 还是 CommonJS 处理,还取决于最近的 package.json 是否包含 "type": "module";不要在未评估现有导入方式时修改该字段。
关键字段
| 字段 | 读取方法 |
|---|---|
target、lib |
控制生成语法与标准库类型,不提供 Node.js API 类型 |
module |
必须匹配实际运行时,不应只因使用 import 就设为 esnext |
rootDir、outDir |
控制输出目录映射;rootDir 不选择输入文件 |
strict |
启用严格检查族,新项目建议开启 |
noEmitOnError |
有错误时不写出新产物,但不会删除旧 dist |
types |
限制自动载入的 @types 包 |
include、exclude |
控制初始文件发现;被导入文件仍可能进入项目 |
验证最终配置
脚本会创建唯一临时源码和配置快照,退出时自动清理。它会展开继承与默认值,并执行一次无输出类型检查。
set -e
npm install --save-dev @types/node --silent --no-audit --no-fund
mkdir -p src
# 使用进程号降低覆盖现有文件的风险。
check_file="src/tsconfig-check-$$.ts"
effective_file=".tsconfig-effective-$$.json"
printf 'const ok: boolean = true;\nconsole.log(ok);\n' > "$check_file"
trap 'rm -f "$check_file" "$effective_file"' EXIT
# --showConfig 输出真正生效的合并结果。
npx tsc --showConfig > "$effective_file"
node --input-type=commonjs -e 'const fs=require("node:fs"); const c=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); console.log(`${c.compilerOptions.module} ${c.compilerOptions.rootDir} ${c.compilerOptions.outDir} strict=${c.compilerOptions.strict}`)' "$effective_file"
npx tsc --noEmit && echo "type-check passed"预期输出
node20 ./src ./dist strict=true
type-check passed路径显示形式可能随工作目录或 TypeScript 版本略有差异。若关键值不一致,检查当前目录、extends 覆盖关系,以及命令是否通过 -p 指向了其他配置。
风险与边界
exclude 不是隔离边界,无法阻止被源码 import 的文件进入编译。需要隔离测试、脚本或生成代码时,应拆分配置并使用不同的 include,而不是只追加排除规则。
skipLibCheck: true 会跳过声明文件内部检查,能缩短构建时间,但可能隐藏依赖声明冲突。升级编译器或依赖后出现异常时,可临时改为 false 定位问题。
noEmitOnError 只阻止本次写出,不清理旧产物。构建失败后继续发布已有 dist,可能部署过期代码;安全做法是让流水线只发布本次成功构建产生的独立制品。
兼容性
TypeScript 5.9 以下不支持 module: "node20"。固定 Node.js 18 可使用 node18;需要跟随较新 Node.js 行为时可评估 nodenext。由 Vite、Webpack 或 Rollup 解析模块的前端项目,通常使用 module: "esnext" 与 moduleResolution: "bundler"。
验证整份配置时使用 npx tsc --showConfig 和 npx tsc --noEmit。不要用 npx tsc <FILE> 代替项目检查,因为显式文件参数会绕过常规 tsconfig.json 项目流程。
使用 tsc 将 TypeScript 编译为 JavaScript。
运行 TypeScript 编译
用于把 .ts 源文件做类型检查并转换为 .js。项目内优先安装 TypeScript,并通过 npx tsc 调用项目锁定版本,避免全局编译器与依赖版本不一致。
基本语法
npx tsc [文件或编译选项]直接指定文件适合临时编译;按项目构建应使用 -p 读取 tsconfig.json。常用参数包括:-p <PATH> 指定配置,--noEmit 只检查不生成文件,--watch 持续监听,--showConfig 查看合并后的最终配置。
高频用法
下面创建最小项目,编译 src/index.ts 并执行生成结果。示例适用于 macOS、Linux 或 Git Bash,前置条件是已安装 Node.js 和 npm。
mkdir ts-demo
cd ts-demo
npm init -y
npm install --save-dev typescript
mkdir src
printf 'const message: string = "hello TypeScript";\nconsole.log(message);\n' > src/index.ts
# 调用项目本地编译器,并把 JavaScript 输出到 dist
npx tsc src/index.ts --target ES2020 --module commonjs --outDir dist
node dist/index.js预期输出:
hello TypeScript编译成功时 tsc 通常保持静默,生成文件位于 dist/index.js。类型错误会显示文件、行列号和 TS 错误码,例如 src/index.ts(1,7): error TS2322,优先处理日志中的第一条根因错误。
风险与边界
执行 npx tsc app.ts 会进入单文件编译模式,项目配置不会按常规项目模式加载,可能丢失目标版本、模块格式、路径映射和输出目录。正式构建使用 npx tsc -p tsconfig.json,临时编译则显式写全关键选项。
若项目未启用 noEmitOnError,报告类型错误时仍可能留下 JavaScript,后续脚本可能误发布错误产物。生产构建应启用该配置,并让 CI 根据 tsc 的非零退出码停止流程。
--watch 会让进程持续等待文件变化,在 CI 或部署脚本中会导致任务不退出。此类环境使用一次性的 npx tsc -p tsconfig.json。
排障清单
- 找不到
tsc:安装开发依赖typescript,再执行版本查询;正常结果形如Version <VERSION>。 - 配置未生效:确认命令没有同时传入源文件,并用
--showConfig检查最终配置。 - 编译成功但无输出:检查
outDir、include、exclude、noEmit和noEmitOnError。 - 运行时报模块错误:核对
module与 Node.js 项目的 CommonJS 或 ESM 设置。
兼容性
编译命令跨平台一致,但示例中的 printf 是 POSIX Shell 写法。Windows PowerShell 可手动创建 src/index.ts,之后继续使用相同的 npx tsc 和 node 命令。
声明 string、number、boolean 等基础类型。
定义 TypeScript 基础类型
使用类型标注约束变量、参数和返回值,让赋值错误在编译阶段暴露。局部常量可依赖类型推断;函数边界、共享数据和外部输入应优先明确类型。
基本语法
类型标注写在标识符后,形式为 名称: 类型。
| 类型 | 典型值 | 说明 |
|---|---|---|
string |
"Ada" |
文本 |
number |
42、3.14 |
整数和浮点数 |
boolean |
true、false |
布尔值 |
bigint |
9007199254740993n |
大整数,末尾带 n |
symbol |
Symbol("id") |
唯一标识 |
null / undefined |
null、undefined |
严格模式下需显式声明 |
高频用法
将以下内容保存为 basics.ts。示例覆盖变量、函数参数、返回值和运行时类型观察。
const userName: string = "Ada";
const age: number = 36;
const active: boolean = true;
// number 同时表示整数和浮点数;超大整数改用 bigint
const score: number = 98.5;
const total: bigint = 9007199254740993n;
const uniqueKey: symbol = Symbol("user");
const emptyValue: null = null;
let pendingValue: undefined = undefined;
function formatUser(name: string, years: number, enabled: boolean): string {
return `${name}:${years}:${enabled}`;
}
console.log(formatUser(userName, age, active));
console.log(score, typeof total, typeof uniqueKey, emptyValue, pendingValue);编译并运行:
npx tsc basics.ts --strict --target ES2020 --module commonjs
node basics.js预期输出:
Ada:36:true
98.5 bigint symbol null undefined初始化值足够明确时可省略标注,例如 const city = "Shanghai" 会推断为 string。可空值使用联合类型,如 string | null,不要依赖宽松的空值规则。
风险与边界
不要使用 String、Number、Boolean 包装对象作为常规类型;它们与小写原始类型的赋值和运行时行为不同。统一使用 string、number、boolean。
number 基于 JavaScript 浮点数,金额小数或超出安全整数范围时可能丢失精度。金额可存最小货币单位整数,超大整数使用 bigint;number 与 bigint 不能直接混算。
any 会关闭后续检查,使错误延迟到运行时。外部 JSON 或第三方返回值优先标为 unknown,经 typeof、字段检查或校验库收窄后再使用。
关闭 strictNullChecks 会让空值混入大量类型。新项目应启用 strict;旧项目先为真实可空字段补充联合类型,再逐步收紧。
兼容性
bigint 示例要求 target 至少为 ES2020,symbol 需要 ES2015 及以上库支持。TypeScript 类型在编译后会被擦除,因此运行时的 typeof 不能验证接口、联合类型或自定义别名。
定义数组元素类型和固定结构元组。
使用数组与元组类型
数组用于保存数量可变、元素类型一致的数据;元组用于描述长度和位置含义固定的数据。坐标、键值对、函数多返回值适合元组,普通列表适合数组。
基本语法
数组写成 T[] 或 Array<T>;只读输入写成 readonly T[]。元组写成 [T1, T2],可添加元素标签和末尾可选项,例如 [name: string, age: number, active?: boolean]。需要保留字面量位置类型时,可在值后使用 as const。
主示例
type Point = readonly [x: number, y: number];
function average(values: readonly number[]): number {
if (values.length === 0) {
throw new Error("values 不能为空");
}
return values.reduce((sum, value) => sum + value, 0) / values.length;
}
const scores: number[] = [80, 90, 100];
const user: [name: string, age: number, active?: boolean] = [
"Ada",
36,
true
];
const originPoint: Point = [0, 0];
console.log(average(scores));
console.log(`${user[0]}:${user[1]}:${user[2] ?? false}`);
console.log(originPoint.join(","));运行命令:
npx tsc array-tuple.ts --target ES2020 --module commonjs --strict
node array-tuple.js预期输出:
90
Ada:36:true
0,0average 只读取参数,因此可同时接收普通数组和只读数组。user[0] 固定为字符串,user[1] 固定为数字,第三项可能不存在;originPoint 不能通过索引重新赋值。
高频用法
需要持续增删同类元素时使用 T[];函数不应修改调用方数据时使用 readonly T[];返回两三个位置固定的值时使用元组。字段较多或以后可能扩展时,改用对象类型,避免调用方依赖下标。
字面量若被推断为 (string | number)[],可在创建处显式标注元组类型,或写成 const pair = ["ok", 200] as const。不要把未经校验的普通数组直接断言成元组。
风险与排障
元组和 readonly 都主要是编译期约束,运行时仍是普通数组;外部 JSON 必须检查长度和元素类型。readonly 还是浅只读,元素内部对象仍可能变化,需要运行时冻结时使用副本配合 Object.freeze。
- 元组长度报错:检查可选元素是否位于必选元素之后,剩余元素是否放在末尾。
- 只读数组调用
sort、push报错:先复制为[...values],再在副本上修改。 - 元素类型不匹配:检查是否混入其他类型,必要时在变量创建处显式标注
T[]。
速查:同类可变集合用数组,固定位置结构用元组,只读参数优先使用 readonly。
描述对象属性、可选字段和只读字段。
定义对象类型
对象类型用于约束属性名称、值类型以及字段是否可缺省或只读。稳定业务结构通常使用 interface 或 type,动态键值集合使用 Record 或索引签名。
基本语法
普通属性写成 name: string,可选属性写成 email?: string,只读属性写成 readonly id: string。interface 适合可扩展对象契约和类实现;type 还能表达联合、交叉、元组和映射类型。仅描述普通对象时二者都可用。
主示例
interface User {
readonly id: string;
name: string;
email?: string;
}
type UserPatch = Partial<Pick<User, "name" | "email">>;
function describe(user: User): string {
return `${user.id}|${user.name}|${user.email ?? "no-email"}`;
}
function updateUser(user: User, patch: UserPatch): User {
return { ...user, ...patch };
}
const original: User = {
id: "u-100",
name: "Ada"
};
const updated = updateUser(original, {
email: "ada@example.com"
});
console.log(describe(original));
console.log(describe(updated));运行命令:
npx tsc object-types.ts --target ES2020 --module commonjs --strict
node object-types.js预期输出:
u-100|Ada|no-email
u-100|Ada|ada@example.comemail 缺失时读取结果可能为 undefined,示例通过 ?? 提供默认值。更新函数创建新对象,不修改原对象;尝试给 original.id 重新赋值会在编译阶段报错。
高频用法
配置、接口参数和实体结构可定义命名 interface。从已有类型选择或调整字段时,使用 Pick、Omit、Partial、Required 和 Readonly。动态键名且值类型统一时,可写 Record<string, number>,不要默认退回 any。
启用 exactOptionalPropertyTypes 后,email?: string 表示属性缺失或值为字符串,不自动接受 { email: undefined };确实需要显式 undefined 时写成 email?: string | undefined。
风险与排障
readonly 是浅层、编译期约束,不会自动冻结运行时对象。TypeScript 又采用结构类型系统:对象只要包含所需字段通常即可赋值,多余字段不会被自动删除。
接口响应、环境变量和反序列化 JSON 都是不可信输入。value as User 只改变编译器视角,不会验证字段;安全做法是在边界处使用类型守卫或运行时校验库。
- “属性不存在”:先检查拼写和联合类型分支,再做类型收窄。
- “可能为 undefined”:确认字段是否应为可选,并在读取处处理缺失情况。
- 对象字面量额外属性报错:修正字段或目标类型,不要用断言掩盖拼写错误。
- 修改只读字段报错:返回包含新值的新对象,而不是原地赋值。
速查:稳定对象契约用 interface 或 type,可能缺失用 ?,禁止重新赋值用 readonly,外部数据必须运行时校验。
通过接口定义对象结构和扩展关系。
使用接口 interface
当多个对象需要遵守同一结构,或类型需要被类实现、被其他接口扩展时,使用 interface。它适合描述对象成员、可选字段、只读字段和方法签名,并能在编译阶段提前发现缺字段或字段类型不匹配。
基本语法
接口只描述类型,不会生成运行时代码。属性后的 ? 表示可选,readonly 表示赋值后不能再次修改,方法可以写成普通方法签名。
interface User {
readonly id: number;
name: string;
email?: string;
greet(prefix: string): string;
}User 要求对象至少包含 id、name 和 greet;email 可以省略。readonly 只限制 TypeScript 代码中的重新赋值,不会在运行时冻结对象。
高频用法
接口最常用于约束对象参数、扩展已有结构,以及让类显式实现约定。下面的示例可直接保存为 interface-demo.ts。
interface Person {
readonly id: number;
name: string;
nickname?: string;
}
interface Employee extends Person {
department: string;
describe(): string;
}
class Developer implements Employee {
constructor(
public readonly id: number,
public name: string,
public department: string,
public nickname?: string
) {}
describe(): string {
const displayName = this.nickname ?? this.name;
return `${displayName} works in ${this.department}`;
}
}
function printEmployee(employee: Employee): void {
console.log(employee.describe());
}
printEmployee(new Developer(101, "Lin", "Platform", "L"));运行编译后的 JavaScript:
npx tsc interface-demo.ts --target ES2020 --module commonjs
node interface-demo.js预期输出:
L works in Platform读取结果时,只要能正常编译并打印部门信息,就说明对象、继承关系和类实现均满足接口约束。npx tsc 可能使用项目中已安装的 TypeScript;未安装时需先执行 npm install --save-dev typescript。
扩展与声明合并
接口可通过 extends 组合多个对象结构,也支持同名声明合并。声明合并适合扩展第三方类型,但同名属性必须保持兼容,否则会产生编译错误。
interface WindowConfig {
theme: "light" | "dark";
}
interface WindowConfig {
language: string;
}
const config: WindowConfig = {
theme: "dark",
language: "zh-CN"
};合并后的 WindowConfig 同时要求 theme 和 language。如果只是业务内部组合类型,优先显式使用 extends,可减少同名声明被意外合并的风险。
风险与边界
对象字面量会触发额外属性检查。直接把含未知字段的字面量赋给接口类型时可能报错;安全做法是修正字段、扩展接口,或先验证外部数据后再转换,不要用类型断言强行绕过。
readonly、接口和类型注解都只在编译阶段生效。来自接口响应、配置文件或用户输入的数据仍需在运行时校验;否则即使写成 User,实际值仍可能缺字段。需要联合类型、元组、条件类型或复杂映射时,通常使用 type 更直接。
排障清单
出现“属性不存在”或“类型不兼容”时,依次检查属性名大小写、必填字段是否遗漏、方法参数与返回值是否一致、extends 后是否产生冲突。类实现接口失败时,还要确认成员访问级别不能比接口更严格,并检查构造参数属性是否正确声明为 public。
创建可复用类型别名和组合类型。
使用类型别名 type
需要为联合类型、交叉类型、元组、函数签名或复杂泛型表达式命名时,使用 type。它既能描述对象,也能组合多个类型,适合把重复出现的类型表达式提取成可复用名称。
基本语法
类型别名使用 type 名称 = 类型表达式 定义。它不会创建新的运行时值,也不会自动校验外部数据。
type Identifier = string | number;
type Point = {
x: number;
y: number;
};
type Formatter = (value: Identifier) => string;Identifier 是联合类型,表示值只能是 string 或 number;Point 描述对象结构;Formatter 描述函数参数和返回值。
高频用法
联合类型配合字面量字段可形成可辨识联合,让分支处理既清晰又具备穷尽检查。下面的示例可直接保存为 type-demo.ts。
type Success = {
status: "success";
data: string;
};
type Failure = {
status: "failure";
error: string;
};
type Result = Success | Failure;
function formatResult(result: Result): string {
if (result.status === "success") {
return `Data: ${result.data}`;
}
return `Error: ${result.error}`;
}
const results: Result[] = [
{ status: "success", data: "compiled" },
{ status: "failure", error: "invalid token" }
];
for (const result of results) {
console.log(formatResult(result));
}运行编译后的 JavaScript:
npx tsc type-demo.ts --target ES2020 --module commonjs
node type-demo.js预期输出:
Data: compiled
Error: invalid token读取结果时,status 会自动收窄类型:成功分支只能访问 data,失败分支只能访问 error。这比把所有字段都设为可选更安全。
组合类型
交叉类型使用 & 合并多个约束,常用于给已有结构追加公共字段。所有组成类型都必须同时满足。
type Timestamped = {
createdAt: Date;
};
type Account = {
id: number;
name: string;
};
type StoredAccount = Account & Timestamped;
const account: StoredAccount = {
id: 7,
name: "Kai",
createdAt: new Date("2026-08-05T00:00:00Z")
};元组和字面量联合也适合用类型别名,例如 type Coordinate = [number, number]、type Mode = "dev" | "test" | "prod"。这些表达式通常无法用单个接口自然表示。
风险与边界
交叉类型不是对象覆盖。若两个成员定义同名属性且类型冲突,例如 { id: string } & { id: number },最终 id 会变成无法正常赋值的 never。安全替代方案是先统一字段定义,或用 Omit 去掉冲突字段后再组合。
类型断言不会执行运行时转换。把未知数据写成 payload as Result 只会关闭部分编译检查,可能在运行时访问不存在的字段。外部输入应先通过手写守卫、Schema 校验库或明确的解析函数验证。
类型别名不能像接口那样通过同名声明自动合并。重复定义同名 type 会报错;需要开放扩展的公共对象契约时优先使用 interface,需要联合、元组、映射和条件类型时优先使用 type。
排障清单
出现联合类型无法访问字段时,先用 typeof、in 或字面量判别字段收窄类型。出现交叉类型赋值失败时,检查同名属性是否冲突。出现“重复标识符”时,确认是否重复声明了同名类型别名。复杂泛型错误难以定位时,可先把嵌套表达式拆成多个中间类型,再逐层查看推导结果。
组合多个类型并表达复杂数据结构。
使用联合与交叉类型
联合类型 A | B 表示值可以属于多个候选类型之一;交叉类型 A & B 表示同一个值必须同时满足多个类型。联合类型适合表达多种输入形态,交叉类型适合把基础字段、审计字段和业务字段组合成完整对象。
基本语法
string | number 允许字符串或数字。访问联合类型成员时,只能直接读取各候选类型共有的属性;访问某个分支的专有属性前,必须通过 typeof、in、判别字段或自定义类型守卫完成收窄。交叉类型会合并全部约束,赋值时不能缺少任一组成类型要求的字段。
type Id = string | number;
type Auditable = {
createdAt: Date;
updatedAt: Date;
};
type User = {
kind: 'user';
id: Id;
name: string;
} & Auditable;
type Service = {
kind: 'service';
id: Id;
endpoint: string;
} & Auditable;
type Subject = User | Service;
function describe(subject: Subject): string {
const id = String(subject.id);
// 先按判别字段收窄,随后才能安全读取分支专有属性。
if (subject.kind === 'user') {
return `user:${id}:${subject.name}`;
}
return `service:${id}:${subject.endpoint}`;
}
const now = new Date('2026-01-01T00:00:00Z');
console.log(
describe({
kind: 'user',
id: 42,
name: 'Ada',
createdAt: now,
updatedAt: now,
}),
);
console.log(
describe({
kind: 'service',
id: 'api',
endpoint: '/health',
createdAt: now,
updatedAt: now,
}),
);预期输出:
user:42:Ada
service:api:/health读取时先看 kind 判断当前分支,再读取该分支的专有字段;createdAt 和 updatedAt 来自交叉类型,两种分支都必须提供。
高频用法
接口结果存在“成功或失败”“用户或服务”等互斥结构时,优先使用带字面量判别字段的联合类型。公共能力需要叠加到多个业务对象时,可用 Base & Auditable & Permission 组合类型。函数参数只接受少量固定值时,可直接使用 'start' | 'stop' 这类字面量联合。
风险与边界
交叉类型不是对象覆盖。若写成 { id: string } & { id: number },属性 id 会被推导为 never,对象将无法正常构造;安全方案是统一字段类型,或把含义不同的冲突字段改名。
不要用类型断言强行绕过联合类型检查。触发条件通常是对象缺少判别字段,或代码尚未完成类型收窄;强制断言可能让程序在运行时访问不存在的属性。应补充稳定的判别字段,或编写能够实际检查数据的类型守卫。
排障清单
出现 Property ... does not exist 时,检查是否在收窄前访问了分支专有字段。出现 Type ... is not assignable to type never 时,检查交叉类型中是否存在同名且不兼容的属性。出现缺少字段错误时,确认对象是否满足交叉类型的全部组成部分,而不是只满足其中一个。
定义具有固定取值集合的枚举类型。
使用枚举 enum
enum 用于声明一组有名称的固定取值,并在运行时生成可访问的 JavaScript 对象。需要统一协议状态、日志级别或业务阶段时,优先使用字符串枚举,使调试输出、接口数据和持久化值保持稳定且易读。
基本语法
字符串枚举的每个成员都要显式赋值;数字枚举可以自动递增,但序号容易因插入成员而变化。业务数据、接口字段和数据库值通常使用字符串枚举,数字枚举更适合只在进程内部使用且不会持久化的序号。
enum LogLevel {
Error = 'ERROR',
Warn = 'WARN',
Info = 'INFO',
}
function shouldAlert(level: LogLevel): boolean {
return level === LogLevel.Error;
}
console.log(LogLevel.Warn);
console.log(shouldAlert(LogLevel.Error));
console.log(Object.values(LogLevel).join(','));预期输出:
WARN
true
ERROR,WARN,INFOLogLevel.Warn 读取运行时值 WARN;Object.values(LogLevel) 可用于生成选项列表。外部传入的普通字符串不会自动成为枚举成员,使用前仍需校验。
高频用法
接口字段和持久化字段使用字符串枚举,并显式固定每个成员的值。条件分支使用 LogLevel.Error 等成员,不要在业务代码中散落硬编码字符串。需要遍历字符串枚举时,可读取 Object.values(LogLevel)。
数字枚举会生成名称到数字、数字到名称的双向映射,因此遍历结果可能同时包含成员名称和数值。需要直接生成下拉选项或校验集合时,字符串枚举通常更简单。
风险与边界
数字枚举默认从 0 开始递增。在成员中间插入新值会改变后续序号;若旧序号已写入数据库、缓存或网络协议,可能导致数据含义错位。安全替代方案是为每个数字成员显式赋值,或改用字符串枚举。
const enum 会在编译时内联成员值。共享库存在不同版本依赖,或项目启用了 isolatedModules、仅转译而不执行完整类型分析时,可能出现编译失败或运行值与声明版本不一致。更稳妥的方案是使用普通 enum,或改用 as const 对象配合字面量联合类型。
排障清单
出现“字符串不能赋给枚举类型”时,不要直接用 as LogLevel 跳过检查;应通过类型守卫验证输入是否存在于 Object.values(LogLevel) 中。遍历数字枚举得到重复项时,应过滤数字键,或改用字符串枚举。发现构建产物包含额外枚举对象时,说明普通 enum 会生成运行时代码;只需要编译期约束时,可改用字符串字面量联合。
声明函数参数、返回值和回调类型。
定义函数类型
用于约束函数的参数顺序、参数类型和返回值,也适合为回调函数、事件处理器和策略函数建立可复用契约。优先使用类型别名描述函数签名;只在需要对象成员或可扩展声明时使用接口。
基本语法
type Formatter = (name: string, score: number) => string;
const formatScore: Formatter = (name, score) => {
return `${name}: ${score}`;
};
console.log(formatScore("Ada", 98));预期输出:
Ada: 98赋值时,参数名可以不同,但参数位置和类型必须兼容;返回值必须能赋给声明的返回类型。启用 strict 后,错误参数或返回值通常会在编译期直接暴露。
高频用法
回调参数应直接写出函数签名,让调用方获得参数推断和返回值检查。
function filterValues(
values: number[],
predicate: (value: number, index: number) => boolean
): number[] {
return values.filter(predicate);
}
const result = filterValues([3, 8, 13, 20], (value, index) => {
return value >= 10 && index % 2 === 0;
});
console.log(result);预期输出:
[ 13 ]可选参数写成 arg?: Type,剩余参数写成 ...args: Type[]。默认参数在调用侧同样可省略,但函数类型通常仍写为可选参数,避免把实现细节暴露给调用方。
风险与边界
void 返回类型表示调用方忽略返回值,不等于实现函数绝对不能返回值;不要用它验证“没有返回语句”。参数过多且含义接近时,位置传参容易错位,安全替代方案是改为单个对象参数。
开启 strictFunctionTypes 后,回调参数的兼容性检查更严格。若赋值失败,不要用 any 或强制断言绕过;先确认回调接收的参数范围是否比调用方实际传入的范围更窄。
排障清单
- 出现“参数数量不匹配”时,检查必选参数、可选参数和剩余参数的位置。
- 出现“不能赋给返回类型”时,检查所有分支是否都返回兼容值。
- 回调参数被推断为
any时,确认函数参数本身是否声明了完整回调签名。 - 同一函数需要多组调用形式时,使用函数重载,不要堆叠大量联合类型。
编写支持多种类型的通用代码。
使用泛型
泛型用于在保留类型信息的前提下复用函数、类型和类。先让 TypeScript 从实参推断类型;只有推断不准确或调用方需要显式约束时,才手动传入类型参数。
基本语法
function firstOrThrow<T>(items: T[]): T {
const first = items[0];
if (first === undefined) {
throw new Error("items must not be empty");
}
return first;
}
const firstName = firstOrThrow(["Ada", "Grace"]);
const firstPort = firstOrThrow([3000, 8080]);
console.log(firstName.toUpperCase());
console.log(firstPort + 1);预期输出:
ADA
3001T 会分别推断为 string 和 number,因此返回值仍保留具体类型。泛型的价值不是“接受任意值”,而是建立输入与输出之间的类型关系。
泛型约束
当实现依赖某个字段或能力时,使用 extends 限制类型参数,而不是在函数内部强制断言。
type HasId = {
id: string;
};
function indexById<T extends HasId>(items: T[]): Map<string, T> {
return new Map(items.map((item) => [item.id, item]));
}
const users = indexById([
{ id: "u1", name: "Ada" },
{ id: "u2", name: "Grace" }
]);
console.log(users.get("u2")?.name);预期输出:
Grace约束只要求对象至少包含 id: string,额外字段会完整保留,因此 users.get("u2") 的值仍包含 name。
常用写法
- 多个类型参数:
function mapValue<T, U>(value: T, mapper: (value: T) => U): U。 - 泛型接口:
interface ApiResponse<T> { data: T; error?: string }。 - 默认类型参数:
type Result<T = unknown> = { value: T }。 keyof约束键名:K extends keyof T,用于安全读取对象属性。
风险与边界
不要把无关的参数都绑定到同一个 T,否则调用方会被迫传入相同类型。不能建立输入输出关系时,优先使用具体类型、联合类型或 unknown,不要为了“通用”而添加泛型。
在 .tsx 文件中,箭头函数的 <T> 可能被解析为 JSX。安全写法是使用函数声明,或写成 const identity = <T,>(value: T): T => value。
排障清单
- 推断结果过宽时,检查数组或对象是否在声明阶段已被扩大为联合类型。
- 提示属性不存在时,为
T添加最小必要约束,不要直接断言。 - 返回值丢失具体字段时,确认返回类型是否错误写成了约束类型本身。
- 泛型调用过于复杂时,减少类型参数数量,并把稳定结构提取为命名类型。
根据条件判断缩小联合类型范围。
使用类型收窄
当变量是联合类型、unknown 或可空类型时,先用运行时可验证的条件缩小范围,再访问分支专属属性。收窄不会改变实际值,只会让 TypeScript 在当前控制流中获得更精确的静态类型。
基本语法
| 判断方式 | 适用场景 | 典型写法 |
|---|---|---|
typeof |
string、number、boolean、bigint、symbol、function、undefined |
typeof value === "string" |
| 相等判断 | 字面量联合、null、undefined |
status === "ok"、value != null |
in |
判断对象是否具有某个属性 | "message" in result |
instanceof |
类实例、Date、Error 等 |
error instanceof Error |
| 判别字段 | 具有共同字面量字段的对象联合 | switch (result.status) |
| 类型谓词 | 需要复用的自定义检查 | value is User |
typeof null 的结果是 "object",检查对象时应同时排除 null。数组也属于对象,需要用 Array.isArray(value) 单独识别。
高频用法
联合对象优先设计稳定的判别字段,例如 status、kind 或 type,然后使用 switch 收窄。处理外部输入时从 unknown 开始,通过 typeof、Array.isArray 和属性检查逐层验证。处理可空值时,使用 value != null 可同时排除 null 与 undefined。
复杂判断可以封装为类型谓词,但谓词实现必须真的验证所声明的结构;编译器会信任返回类型,错误谓词会把风险推迟到运行时。
完整示例
以下示例使用判别联合处理三种支付结果,并用 never 检查分支是否穷尽。保存为 narrow.ts。
type PaymentResult =
| { status: "ok"; transactionId: string }
| { status: "failed"; reason: string }
| { status: "pending"; retryAfterMs: number };
function describe(result: PaymentResult): string {
switch (result.status) {
case "ok":
return `paid:${result.transactionId}`;
case "failed":
return `failed:${result.reason}`;
case "pending":
return `retry:${result.retryAfterMs}ms`;
default: {
// 新增联合成员却忘记处理时,这里会产生编译错误。
const exhaustive: never = result;
return exhaustive;
}
}
}
const results: PaymentResult[] = [
{ status: "ok", transactionId: "tx-42" },
{ status: "failed", reason: "insufficient-funds" },
{ status: "pending", retryAfterMs: 3000 }
];
for (const result of results) {
console.log(describe(result));
}运行命令如下,项目需已安装 typescript。
npx tsc --strict --target ES2020 --module commonjs narrow.ts
node narrow.js预期输出:
paid:tx-42
failed:insufficient-funds
retry:3000ms读取结果时,三行分别对应 ok、failed 和 pending 分支;每个分支只能访问该成员实际拥有的字段。
风险与边界
使用真值判断收窄字符串或数字时,""、0、false 会被一并排除,可能误把合法值当成缺失值。安全替代是显式判断 value !== undefined、value !== null 或具体字面量。
"prop" in value 只能证明属性存在于对象或原型链上,不能证明属性值类型正确;可选属性还可能出现在多个联合成员中。外部数据应继续检查属性值,或使用可靠的校验函数。
对象在回调、异步边界或赋值后可能发生变化,编译器会撤销此前的部分收窄。需要稳定值时先保存到局部常量,或在使用点重新检查。
排障清单
- 出现“属性不存在”时,确认访问发生在正确分支内,并检查判别字段是否被推断成普通
string而不是字面量。 never穷尽检查报错时,通常表示联合类型新增了成员但switch尚未处理;补充分支,不要删除检查。- 自定义谓词通过编译但运行时报错时,逐项核对谓词是否验证了所有必需字段及其值类型。
- 收窄进入函数后失效时,把参数类型设计为更具体的成员类型,或在函数内部重新执行检查。
在明确场景下手动指定值的类型。
使用类型断言
类型断言用于在你掌握额外运行时事实时,告诉 TypeScript 按指定类型检查某个值。它只影响编译阶段,不会转换数据、补齐字段或执行校验,因此应放在已验证的边界之后,而不是用来压掉不理解的类型错误。
基本语法
| 写法 | 作用 | 注意 |
|---|---|---|
value as Type |
把表达式视为指定类型 | TSX 文件中优先使用此写法 |
value as const |
保留字面量并把对象、数组推断为只读窄类型 | 适合配置常量和判别字段 |
value! |
非空断言,排除 null 与 undefined |
不是运行时检查,值为空仍会报错 |
尖括号写法 <Type>value 在普通 .ts 文件中可用,但在 .tsx 中会与 JSX 语法冲突。团队项目通常统一使用 as,减少文件类型切换时的解析问题。
高频用法
解析 JSON、读取第三方 SDK 返回值或访问框架注入对象时,可以先把结果视为 unknown,完成结构校验后再断言。操作 DOM 时,只有页面结构由当前代码严格控制,且无法通过泛型 API 表达时才断言具体元素类型。
常量对象需要保留字面量类型时使用 as const。若只是想验证对象符合某个类型,同时保留更精确的推断,优先使用 satisfies,不要把整个对象宽化成目标类型。
完整示例
以下示例先验证 JSON 的运行时结构,再使用断言获得 User 类型。保存为 assertion.ts。
interface User {
id: string;
active: boolean;
}
const parsed: unknown = JSON.parse('{"id":"u-42","active":true}');
function hasUserShape(value: unknown): boolean {
if (typeof value !== "object" || value === null) {
return false;
}
// 这里只把未知对象临时视为键值表,随后仍逐项验证字段。
const record = value as Record<string, unknown>;
return typeof record.id === "string"
&& typeof record.active === "boolean";
}
if (!hasUserShape(parsed)) {
throw new Error("invalid user payload");
}
// 断言建立在上面的运行时校验结果之上。
const user = parsed as User;
console.log(`${user.id}:${user.active}`);运行命令如下,项目需已安装 typescript。
npx tsc --strict --target ES2020 --module commonjs assertion.ts
node assertion.js预期输出:
u-42:true输出表示断言后的对象可以按 User 读取;若 JSON 缺少字段或字段类型错误,程序会先抛出 invalid user payload,不会继续使用不可信数据。
风险与边界
直接把外部数据写成 payload as User 时,触发条件是数据来源未校验;后果可能是访问缺失字段、调用不存在的方法或把错误值写入后续系统。安全替代是先使用类型守卫、断言函数或运行时校验库验证结构。
使用 value as unknown as Target 可以绕过类型重叠检查,但这通常意味着源类型和目标类型并不兼容。除非在封装底层桥接层且有独立测试证明契约,否则应修正类型定义或显式转换数据。
非空断言 value! 在值实际为 null 或 undefined 时不会提供保护,运行时仍可能崩溃。优先使用条件判断、可选链、默认值,或让初始化流程在类型上保证值已经存在。
断言不会进行数据转换。"42" as unknown as number 的运行时值仍是字符串;需要数字时应调用 Number(value) 并检查结果是否为有限数。
排障清单
- 出现“类型转换可能是错误的”时,不要立即双重断言;先检查源类型、目标类型及缺失字段,必要时写显式转换函数。
- 断言后仍出现
undefined或“不是函数”时,说明运行时契约不成立;回到数据入口增加校验并记录原始载荷。 .tsx中尖括号断言报语法错误时,改用value as Type。- 断言散落在业务代码各处时,把校验与断言集中到 API、存储或消息入口,业务内部只接收已验证类型。
快速生成 Partial、Pick、Omit 等类型。
使用工具类型
当已有对象类型只需“全部可选、挑选部分字段或排除字段”时,优先组合 Partial、Pick 和 Omit,避免重复声明结构。它们只在编译期生成新类型,不会修改运行时对象。
基本语法
Partial<T>:把T的第一层属性全部变为可选,常用于更新参数。Pick<T, K>:仅保留键集合K,适合接口入参或视图模型。Omit<T, K>:排除键集合K,适合隐藏敏感字段或拆分内部类型。Required<T>、Readonly<T>、Record<K, V>可分别恢复必填、限制写入和构造键值映射。
多个工具类型可以嵌套,例如 Partial<Pick<User, "name" | "email">> 表示只允许更新指定字段,并让这些字段全部可选。
高频用法
下面示例用 Partial 定义更新参数,用 Pick 限制可更新字段,再用 Omit 生成公开返回类型。注意:Omit 只改变静态类型,运行时仍需主动删除字段。
type User = {
id: string;
name: string;
email: string;
active: boolean;
};
type UserPatch = Partial<Pick<User, "name" | "email" | "active">>;
type PublicUser = Omit<User, "email">;
function applyPatch(user: User, patch: UserPatch): User {
return { ...user, ...patch };
}
function toPublic(user: User): PublicUser {
const { email: _email, ...publicUser } = user;
return publicUser;
}
function main(): void {
const user: User = {
id: "u-1",
name: "Lin",
email: "old@example.com",
active: true,
};
const updated = applyPatch(user, { email: "new@example.com" });
console.log(JSON.stringify(updated));
console.log(JSON.stringify(toPublic(updated)));
}
main();预期输出:
{"id":"u-1","name":"Lin","email":"new@example.com","active":true}
{"id":"u-1","name":"Lin","active":true}第一行验证补丁只覆盖传入字段;第二行验证公开对象在运行时确实移除了 email。
风险与边界
Partial 是浅层转换:当属性本身是嵌套对象时,只会让外层属性可选,不会递归处理内部字段。需要深度可选时应单独定义受控的递归类型,避免数组、函数和特殊对象被错误展开。
当触发条件是“仅用 Omit 声明返回类型,却直接返回原对象”时,敏感字段仍会存在于运行时结果中,可能造成数据泄露。安全替代方案是显式解构删除字段,或使用经过验证的序列化函数。
排障清单
Type '"x"' does not satisfy the constraint 'keyof T':检查Pick或Omit的键名是否真实存在。- 更新参数意外允许空对象:
Partial<T>本来就允许{},需要至少一个字段时应增加RequireAtLeastOne一类约束。 - 只读属性仍被运行时代码修改:
Readonly<T>仅做编译期限制,需冻结对象时使用Object.freeze并结合不可变更新。
为 JavaScript 模块和第三方库补充类型。
声明模块类型
当 JavaScript 文件或第三方包缺少类型声明,导致导入结果为 any 或出现“找不到声明文件”错误时,为模块补充 .d.ts。本地模块优先使用同名声明文件;外部包才使用 declare module "包名"。
选择声明方式
本地文件 legacy-math.js 对应 legacy-math.d.ts,声明文件直接导出成员,不要写相对路径形式的环境模块声明。第三方包没有内置类型且 DefinitelyTyped 也未提供时,可在项目包含范围内创建环境模块声明。
先检查包自身的 types 或 exports 配置,再尝试安装 @types/<包名>;只有确实缺失时才维护自定义声明,避免与官方类型重复。
本地 JavaScript 模块完整示例
legacy-math.js 提供运行时代码:
exports.add = (a, b) => a + b;同目录创建 legacy-math.d.ts,名称必须与模块文件一致:
export function add(a: number, b: number): number;app.ts 正常导入并获得参数、返回值检查:
import { add } from "./legacy-math";
function main(): void {
console.log(add(2, 3));
}
main();tsconfig.json 让编译器同时复制 JavaScript 文件并检查 TypeScript 调用:
{
"compilerOptions": {
"target": "ES2022",
"module": "CommonJS",
"moduleResolution": "Node",
"strict": true,
"allowJs": true,
"checkJs": false,
"outDir": "dist"
},
"include": ["app.ts", "legacy-math.js", "legacy-math.d.ts"]
}运行:
npx tsc -p tsconfig.json && node dist/app.js预期输出:
5若把调用改为 add("2", 3),编译阶段会报告字符串不能赋给 number,说明声明已经生效。
第三方包声明
下面是片段示例,依赖真实安装的 untyped-sdk。将文件保存为 src/types/untyped-sdk.d.ts,并确保 tsconfig.json 的 include 覆盖该目录:
declare module "untyped-sdk" {
export interface ClientOptions {
endpoint: string;
timeoutMs?: number;
}
export interface Client {
request(path: string): Promise<unknown>;
}
export function createClient(options: ClientOptions): Client;
}验证方法是在业务代码中导入 createClient,再执行 npx tsc --noEmit。参数拼写错误或漏传 endpoint 时应出现类型错误;无错误表示声明文件已被编译器纳入。
风险与边界
仅写 declare module "untyped-sdk"; 会把整个包降级为 any。触发后编译错误暂时消失,但错误参数和错误返回值会绕过检查。安全替代方案是先声明实际使用的最小 API,再随使用范围扩展。
自定义声明与包升级后的真实 API 不一致时,会产生“类型通过、运行时报错”的假安全。升级依赖后应运行类型检查和集成测试;若包后来内置类型或新增 @types,删除自定义声明,避免重复标识符和重载冲突。
排障清单
- 仍提示找不到声明:确认
.d.ts位于include范围内,且未被exclude排除。 - 声明存在但导入成员不匹配:检查模块是默认导出、命名导出还是 CommonJS
export =。 - Node ESM 项目解析异常:核对
module、moduleResolution、文件扩展名和包的exports条件是否一致。 - 使用
typeRoots后声明消失:该选项会限制自动发现目录,应把自定义类型目录和node_modules/@types一并配置。
安装和管理第三方类型声明文件。
处理第三方库类型
当第三方 JavaScript 包缺少类型或类型版本不匹配时,先确认包是否自带声明,再安装对应的 @types 包;只有确实没有可用声明时,才在项目内补最小 .d.ts。最终以 tsc --noEmit 通过为准,不能只看编辑器是否暂时消除红线。
选择类型来源
按以下顺序处理:包自身 package.json 的 types 或 typings、DefinitelyTyped 发布的 @types/*、项目内自维护声明。库已内置类型时不要重复安装 @types,否则可能同时加载两套声明并产生重复标识符或重载冲突。
普通包 lodash 对应 @types/lodash;作用域包 @foo/bar 通常对应 @types/foo__bar。类型包一般放入 devDependencies,因为它只参与开发和编译;但如果你发布的库在公开 .d.ts 中直接引用某个类型包,该类型包应进入 dependencies,避免使用者安装后缺失声明。
安装与验证
下面创建一个最小项目,为 lodash 安装声明并执行纯类型检查。命令使用 Bash,运行后不会生成 JavaScript 文件。
mkdir ts-third-party-types
cd ts-third-party-types
npm init -y >/dev/null
npm install --silent lodash
npm install --silent --save-dev typescript @types/lodash
mkdir src
cat > tsconfig.json <<'JSON'
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"noEmit": true
},
"include": ["src"]
}
JSON
cat > src/index.ts <<'TS'
import lodash = require("lodash");
const result: string = lodash.camelCase("TypeScript types ready");
console.log(result);
TS
npx tsc --noEmit && echo TYPECHECK_OK预期输出
TYPECHECK_OK看到该行表示模块实现和类型声明都已解析,且示例通过严格类型检查。npm install 的进度或审计信息可能因 npm 版本不同而变化,不作为验证依据。
无类型包的本地声明
确认包自身和 @types 都没有声明后,可新增片段示例 src/types/legacy-math.d.ts,只描述项目实际使用的接口。不要只写 declare module "legacy-math";,那会把整个包退化为 any,错误会继续流入业务代码。
declare module "legacy-math" {
export function sum(left: number, right: number): number;
}声明文件需被 include 覆盖,或位于已包含的 src 目录。补完后重新执行前面的 npx tsc --noEmit;无输出且退出码为 0 即验证通过。
风险与边界
| 触发条件 | 可能后果 | 安全替代方案 |
|---|---|---|
库已内置类型仍安装旧版 @types |
重复声明、API 签名冲突 | 删除多余 @types,以库内置声明为准 |
使用 skipLibCheck 掩盖依赖错误 |
构建通过但错误类型进入业务代码 | 先升级或锁定兼容版本,仅将其作为短期止血 |
本地声明写成宽泛 any |
丢失参数和返回值检查 | 只声明实际使用接口,未知值优先用 unknown |
| 类型包与运行包主版本不一致 | 方法缺失、重载不匹配 | 同步升级,必要时用 lockfile 固定已验证组合 |
排障清单
出现 TS7016: Could not find a declaration file 时,依次检查包是否自带 types、是否存在正确命名的 @types、声明文件是否被 include 收录。出现重复标识符时执行 npm ls <包名> @types/<包名> 查找多版本,再删除错误依赖并重装。编辑器仍显示旧错误时,先确认命令行检查结果,再重启 TypeScript Language Service,避免把缓存问题误判成声明错误。
设置 TypeScript 模块解析和路径别名。
配置模块导入
模块导入需要同时匹配 TypeScript 的编译期解析规则和 Node.js 或打包器的运行时规则。正确配置后,类型检查、构建和实际启动都能找到同一个文件;只让编辑器识别别名而不处理运行时,会出现“编译通过、启动时报找不到模块”。
选择模块解析模式
Node.js 原生 ESM 或 ESM/CJS 混合项目使用 module: "NodeNext" 与 moduleResolution: "NodeNext";由 Vite、Rollup、esbuild 或 webpack 完成打包的项目通常使用 module: "ESNext" 与 moduleResolution: "Bundler"。两项应成对设置,不要仅为了消除报错随意混搭。
paths 用于告诉 TypeScript 如何查找类型和源文件,但不会改写输出 JavaScript 中的导入字符串。运行时必须由 package.json 的 imports、打包器 alias 或专用加载器提供同名映射。

可运行的 Node.js 别名方案
下面使用 Node.js 原生 imports 配置 # 别名。#* 映射到构建目录,TypeScript 在 NodeNext 模式下结合 rootDir 和 outDir 将源码解析到 src,运行时则由 Node.js 读取同一份 package.json 映射。
mkdir ts-module-alias
cd ts-module-alias
cat > package.json <<'JSON'
{
"name": "ts-module-alias",
"private": true,
"type": "module",
"imports": {
"#*": "./dist/*"
},
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
}
}
JSON
npm install --silent --save-dev typescript
mkdir src
cat > tsconfig.json <<'JSON'
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true
},
"include": ["src"]
}
JSON
cat > src/math.ts <<'TS'
export const sum = (left: number, right: number): number => left + right;
TS
cat > src/index.ts <<'TS'
import { sum } from "#math.js";
console.log(sum(2, 3));
TS
npm run build --silent
npm start --silent预期输出
5输出 5 表示编译期和运行时都解析到了同一个模块。源码中的 .js 后缀是 Node.js ESM 的运行时路径,TypeScript 会在编译阶段对应查找 .ts 源文件。
使用 paths 的编译期别名
以下是打包器项目的片段示例。它让 TypeScript 把 @/utils 映射到 src/utils,但还必须在 Vite、webpack 或其他打包器中配置相同的 @ -> ./src 映射。
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
"paths": {
"@/*": ["./src/*"]
},
"noEmit": true
}
}验证时先运行 npx tsc --noEmit 检查类型解析,再执行项目真实的构建和启动命令检查运行时。只完成第一步不能证明别名配置正确。
风险与边界
| 触发条件 | 可能后果 | 安全替代方案 |
|---|---|---|
只配置 paths |
类型检查通过,运行时报 MODULE_NOT_FOUND |
在打包器同步 alias,或改用 Node.js imports |
module 与 moduleResolution 不匹配 |
包导出条件、ESM/CJS 判断异常 | Node 项目成对使用 NodeNext,打包器项目使用 ESNext + Bundler |
| NodeNext 的相对 ESM 导入省略扩展名 | 编译报扩展名错误或运行时找不到文件 | 源码导入写输出后的 .js 后缀 |
| 多个 tsconfig 定义不同别名 | 编辑器、测试、构建结果不一致 | 抽出共享基础配置,并让测试工具读取同一映射 |
排障清单
先执行 npx tsc --traceResolution --noEmit,搜索目标模块名,确认 TypeScript 实际尝试了哪些路径。再检查运行产物中的导入字符串是否被保留,以及 Node.js、测试框架和打包器是否各自加载了对应别名。若同一文件在编辑器可跳转但命令行失败,确认当前目录使用的是哪一个 tsconfig.json,并用 npx tsc --showConfig 查看合并后的最终配置。
兼容性
新项目不要依赖 baseUrl 作为隐式查找根目录;TypeScript 6.0 已将其标记为弃用。paths 的目标应直接写成相对 tsconfig.json 的路径。旧 CommonJS 项目可继续使用 module: "CommonJS",但不要与 NodeNext 的 ESM 扩展名和 package.json 条件导出规则混用。
启用 strict 检查提升类型安全。
开启严格模式
在新项目中直接启用 strict,让编译器尽早发现隐式 any、空值使用、函数参数兼容性和类属性初始化等问题。旧项目应先用只检查不产物的方式评估错误量,再分批修复,避免一次切换阻塞发布。
配置方法
在项目根目录的 tsconfig.json 中开启严格检查:
{
"compilerOptions": {
"strict": true,
"noEmitOnError": true
}
}strict 是一组严格类型检查的总开关;noEmitOnError 不属于 strict,这里单独开启,用于阻止存在类型错误时生成新的 JavaScript 产物。配置生效后,先执行只检查不输出文件的验证:
npx tsc --noEmit预期输出:
无输出,进程退出码为 0无输出表示当前项目通过类型检查;出现 error TS<CODE> 时,应按文件、行列和错误码逐项修复。实际路径、行号和错误码会随项目内容不同。
高频用法
新项目直接提交 "strict": true,并在持续集成中固定运行 npx tsc --noEmit。这样开发机与构建环境使用同一套规则,不会等到打包阶段才暴露类型问题。
旧项目迁移时,先在独立分支开启 strict 统计错误,再按目录或模块修复。若一次性错误过多,可暂时分别开启 noImplicitAny、strictNullChecks、strictFunctionTypes 等检查,但最终仍以恢复总开关为目标,避免配置长期漂移。
需要确认继承配置是否覆盖了本地设置时,使用:
npx tsc --showConfig预期结果:
输出合并后的完整编译配置,其中 compilerOptions.strict 应为 true--showConfig 的其他字段由 TypeScript 版本、继承配置和项目文件决定,不应逐字比对整份输出。
风险与边界
在历史代码库直接开启 strict,可能一次产生大量编译错误并阻断构建。安全替代方案是先运行 npx tsc --noEmit 获取基线,在独立分支分模块修复,并让持续集成只检查已迁移范围。
不要用批量添加 any、非空断言 ! 或类型断言 as 来快速清零错误;这些写法会绕过编译器保护,可能把空值、字段缺失和错误数据留到运行期。优先补充真实类型、控制流收窄、默认值或边界数据校验。
排障清单
strict没生效:检查命令是否读取了预期的tsconfig.json,再用npx tsc --showConfig查看最终值。- 编辑器与命令行结果不同:确认工作区 TypeScript 版本、项目根目录和启动配置一致。
- 错误来自依赖声明文件:先升级依赖及其类型包;
skipLibCheck只能作为临时隔离措施,不能替代修复自身代码。 - 构建仍生成产物:确认已设置
noEmitOnError,或在检查阶段固定使用--noEmit。
速查:新项目开启 strict;旧项目先评估、分批迁移;不要用宽泛断言掩盖真实错误。可将 strict 作为项目默认基线,并把临时豁免记录为待清理项。
定位和修复常见 TypeScript 编译错误。
调试类型错误
先用 tsc 获取稳定、完整的诊断信息,再根据“实际类型不能赋给目标类型”的方向定位根因。修复时优先改变数据流、补充收窄或完善声明,不要只靠断言消除红线。
定位命令
在项目根目录运行:
npx tsc --noEmit --pretty false预期输出:
<PATH>(<LINE>,<COLUMN>): error TS<CODE>: <MESSAGE><PATH>、<LINE>、<COLUMN>、<CODE> 和 <MESSAGE> 会随项目变化。先处理最上游错误;一个错误类型或缺失声明,常会在后续文件触发多条连锁诊断。--pretty false 关闭颜色和装饰,便于复制、搜索和交给日志系统解析。
主示例:修复可选字段错误
下面代码把可选属性直接作为必有字符串返回,在严格空值检查下会失败:
type User = {
name?: string;
};
function displayName(user: User): string {
return user.name;
}
console.log(displayName({}));检查命令:
npx tsc --strict --noEmit debug.ts预期输出:
<PATH>(<LINE>,<COLUMN>): error TS2322: Type 'string | undefined' is not assignable to type 'string'.根因不是返回类型写错,而是 name? 明确允许 undefined。根据业务语义提供默认值即可完成收窄:
type User = {
name?: string;
};
function displayName(user: User): string {
return user.name ?? "anonymous";
}
console.log(displayName({}));运行命令:
npx tsc --strict debug.ts --outDir dist && node dist/debug.js预期输出:
anonymous按错误类型处理
TS2322 和 TS2345 通常表示赋值或传参不兼容。先分别写出源类型与目标类型,检查字段是否缺失、联合类型是否未收窄、泛型参数是否推断过宽,再决定修改调用方还是接口定义。
“对象可能为 undefined”类错误应使用存在性判断、可选链或空值合并;只有在运行条件确实保证非空且无法被类型系统表达时,才考虑非空断言。TS7006 表示参数隐式为 any,应补充参数类型或让上下文正确推断。
模块或声明找不到时,不要继续修改业务类型。先确认导入路径、moduleResolution、包的 exports、类型声明文件以及当前配置实际包含的文件;必要时再使用 --traceResolution 专门查看模块解析过程。
风险与边界
as SomeType、!、any 和 @ts-ignore 会压制诊断,却不会验证运行时数据。触发条件通常是外部接口、JSON、环境变量或可选字段未经校验;后果可能是访问不存在字段、空值调用或错误分支永远未处理。
安全替代方案是把不可信输入先声明为 unknown,再用 typeof、in、判别联合或校验函数收窄。确需保留预期错误的测试代码时,优先使用带原因说明的 @ts-expect-error,并限制在单行边界。
排障清单
- 错误位置看似无关:从第一条诊断开始,检查上游类型别名、重载和泛型约束。
- 编辑器报错但
tsc不报:确认编辑器选择了工作区 TypeScript,并打开了同一个项目配置。 tsc检查了不该包含的文件:用--showConfig或--listFilesOnly核对files、include、exclude。- 修复后仍报旧错误:删除构建缓存或重启语言服务,再重新运行命令验证。
速查:先读错误码和源/目标类型,再修复数据流;断言只能用于已被运行条件证明安全的边界。修复完成后始终重新运行完整项目检查,确认没有产生新的连锁错误。