1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// @ts-check
/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} name
 * @property {"admin" | "user"} role
 */

/**
 * 按 ID 查找用户。
 * @param {string} id - 用户 ID
 * @param {{ timeout?: number }} [options] - 选项
 * @returns {Promise<User | null>}
 */
export async function findUser(id, options) {
  // id 和 options 都有类型了 ✅
  const res = await fetch(`/api/users/${id}`, { signal: AbortSignal.timeout(options?.timeout ?? 5000) });
  return res.json();
}

/** @type {User[]} */
const cache = [];

/**
 * @template T
 * @param {T[]} items
 * @param {(item: T) => boolean} pred
 * @returns {T | undefined}
 */
function find(items, pred) { return items.find(pred); }

1
2

// 迁移起点
{ "compilerOptions": { "strict": false } }

1
2
3
4
5
6
7

// 逐项开启（每次只加一个，修完再加下一个）
{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": true      // ← 第一步只加这个
  }
}

1
2
3
4
5
6
7

// 1. 先只在部分目录开（用额外 tsconfig）
// tsconfig.strict.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "strictNullChecks": true },
  "include": ["src/new-feature/**/*"]
}

1
2
3
4
5
6
7

// 2. 或者按目录用 // @ts-strict 之类做不到，就用多配置 + CI 分步检查
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "typecheck:strict": "tsc --noEmit -p tsconfig.strict.json"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// src/types/legacy-analytics.d.ts
declare module "legacy-analytics" {
  export interface TrackOptions {
    userId?: string;
    properties?: Record<string, string | number | boolean>;
  }

  export function track(event: string, options?: TrackOptions): void;
  export function identify(userId: string): void;
  export function flush(): Promise<void>;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// 第 1 步：先让它能编译（最小信息）
declare module "legacy-lib" {
  const lib: unknown;
  export default lib;
}

// 第 2 步：用到什么补什么
declare module "legacy-lib" {
  export function init(config: { key: string }): void;
  export function send(event: string, payload?: unknown): Promise<void>;
}

// 第 3 步：补充更精确的类型
declare module "legacy-lib" {
  export interface InitConfig {
    key: string;
    endpoint?: string;
    debug?: boolean;
  }
  export function init(config: InitConfig): void;
  export function send(event: string, payload?: Record<string, unknown>): Promise<void>;
}

1
2
3
4
5
6

# 1. fork 并克隆 DefinitelyTyped
git clone https://github.com/<你的用户名>/DefinitelyTyped.git
cd DefinitelyTyped

# 2. 创建类型包目录（结构与 npm 包名一致）
mkdir -p types/my-library

1
2
3
4
5
6
7
8
9

// types/my-library/package.json
{
  "name": "@types/my-library",
  "version": "1.0.0",
  "projects": ["https://github.com/author/my-library"],
  "dependencies": {},
  "types": "index.d.ts",
  "typeScriptVersion": "5.0"
}

1
2
3
4
5
6
7
8

// types/my-library/index.d.ts
export interface Options {
  key: string;
  debug?: boolean;
}

export function init(options: Options): void;
export function send(event: string, payload?: Record<string, unknown>): Promise<void>;

1
2
3
4
5

# 3. 测试（DT 提供工具）
npm test          # 或 npx dtslint types/my-library
npx tsc --noEmit  # 类型检查

# 4. 提交 PR

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

遇到 any，按顺序问：

1. 这个值的真实类型我确定吗？
   ├─ 确定 → 写上真实类型 ✅
   └─ 不确定 → 继续

2. 它是「外部来的」吗？（API / JSON / env / 用户输入）
   ├─ 是 → 改 unknown + 运行时校验（见 11）🔥
   └─ 否 → 继续

3. 它能用泛型表达吗？
   ├─ 能 → 用泛型 <T> ✅
   └─ 不能 → 继续

4. 它是「任意对象」吗？
   ├─ 是 → Record<string, unknown> ✅
   └─ 否 → 继续

5. 它是「任意值」吗？
   ├─ 是 → unknown ✅
   └─ 否 → 继续

6. 真的是无法表达 → 保留 any，但加注释说明原因 + TODO

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// 🛑 原代码
function process(data: any) {
  return data.items.map((i: any) => i.name).join(", ");
}

// ✅ 改成 unknown 后，编译器会逼你写清楚
function process(data: unknown): string {
  if (
    typeof data === "object" && data !== null &&
    "items" in data && Array.isArray((data as { items: unknown }).items)
  ) {
    const items = (data as { items: unknown[] }).items;
    return items
      .map((i) => (typeof i === "object" && i !== null && "name" in i
        ? String((i as { name: unknown }).name)
        : ""))
      .join(", ");
  }
  return "";
}

// ✅✅ 更好：用 schema 库，一次到位
import { z } from "zod";

const DataSchema = z.object({
  items: z.array(z.object({ name: z.string() })),
});

function process2(data: unknown): string {
  const parsed = DataSchema.safeParse(data);
  if (!parsed.success) return "";
  return parsed.data.items.map((i) => i.name).join(", ");
}

1
2

# 统计
grep -rn "@ts-ignore\|@ts-expect-error\|@ts-nocheck" src | wc -l

1
2
3
4
5
6
7

// ✅ @ts-expect-error 的正确用法：带原因
// @ts-expect-error 上游库类型定义缺失该重载，见 https://github.com/x/y/issues/123
legacyCall(x);

// 🛑 没有原因的抑制 = 定时炸弹
// @ts-expect-error
legacyCall(x);

1

error TS2578: Unused '@ts-expect-error' directive.

1
2
3
4

// 🛑 危险的 @ts-nocheck：整个文件不再检查
// @ts-nocheck
// TODO(2026-Q2): 迁移本文件，见 #1234
export function legacyStuff(x) { /* ... 全是隐式 any ... */ }

1
2
3
4
5

<!-- docs/ts-migration-todo.md -->
| 文件 | 原因 | 负责人 | 期限 |
| --- | --- | --- | --- |
| `src/legacy/payment.ts` | 依赖已下线的 SDK | @alice | 2026-Q2 |
| `src/legacy/report.ts` | 复杂类型体操失败 | @bob | 2026-Q3 |

1
2
3
4
5
6
7
8

// 典型的前端项目分工
{
  "scripts": {
    "dev": "vite",                        // 快速转译，类型错误不影响 HMR
    "build": "tsc --noEmit && vite build", // 🔥 构建前必须类型检查
    "typecheck": "tsc --noEmit --watch"   // 开发时单独跑
  }
}

1
2
3
4
5
6
7
8
9

// 根 tsconfig.json ——solution 文件
{
  "files": [],
  "references": [
    { "path": "./packages/types" },
    { "path": "./packages/core" },
    { "path": "./packages/web" }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// packages/core/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,          // 🔥 必需
    "declaration": true,        // 🔥 composite 隐含要求
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src"],
  "references": [
    { "path": "../types" }      // 声明依赖
  ]
}

1
2
3

npx tsc --build              # 按拓扑顺序构建所有包
npx tsc --build --watch      # 监听
npx tsc --build --clean      # 清理