全链路 TypeScript 工具库：从开发到部署的全方位指南

┌─────────────────────────────────────────────────────────────┐
│                  TypeScript 工具链全景图                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   开发阶段                           │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  ts-node  │ ts-node-dev  │ tsc-watch  │ esno       │   │
│  │  实时执行  │  热重载      │  文件监听   │ 高速执行   │   │
│  └─────────────────────────────────────────────────────┘   │
│                           ↓                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   类型增强                           │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  type-fest  │ utility-types  │ ts-toolbelt         │   │
│  │  工具类型   │  高级类型      │  类型集合            │   │
│  └─────────────────────────────────────────────────────┘   │
│                           ↓                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   校验阶段                           │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  tsc  │ typescript-eslint  │ zod  │ class-validator │   │
│  │  编译  │ 代码检查           │ 运行时 │ 装饰器校验    │   │
│  └─────────────────────────────────────────────────────┘   │
│                           ↓                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   构建阶段                           │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  ESBuild  │ swc  │ Vite  │ tsup  │ dts-bundle      │   │
│  │  打包     │ 编译  │ 构建工具 │ 库打包 │ 类型打包    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# 安装 ts-node
npm install -D ts-node

# 直接运行 .ts 文件
npx ts-node your-script.ts

# 使用 ESM 模式
npx ts-node --esm your-script.ts

// tsconfig.json
{
  "ts-node": {
    "compilerOptions": {
      "module": "CommonJS",
      "moduleResolution": "node"
    },
    "transpileOnly": true, // 跳过类型检查，提升速度
    "files": true // 加载 tsconfig.json 中的 files
  }
}

# 安装 ts-node-dev
npm install -D ts-node-dev

# 启动开发服务器并监听文件变更
npx ts-node-dev --respawn src/index.ts

# 指定监听目录
npx ts-node-dev --respawn --watch src src/index.ts

# 忽略特定目录
npx ts-node-dev --respawn --ignore node_modules src/index.ts

# 安装
npm install -D tsc-watch

# 编译成功后启动应用
npx tsc-watch --onSuccess "node ./dist/server.js"

# 编译失败时输出提示
npx tsc-watch --onFailure "echo '编译失败，请检查代码！'"

# 完整示例
npx tsc-watch --onSuccess "npm start" --onFailure "npm run notify"

{
  "scripts": {
    "dev": "tsc-watch --onSuccess \"npm start\"",
    "start": "node dist/index.js"
  }
}

# 安装 esno
npm install -D esno

# 使用 esno 运行 .ts 文件
npx esno index.ts

# 作为 Node.js 替代
node --loader esno index.ts

# 安装 typed-install
npm install -g typed-install

# 使用 typed-install 安装依赖
typed-install lodash
# 自动安装 lodash 和 @types/lodash

# 安装多个依赖
typed-install express axios lodash

# 运行 suppress-ts-errors
npx suppress-ts-errors

# 指定使用 @ts-expect-error
npx suppress-ts-errors --ts-expect-error

# 指定项目路径
npx suppress-ts-errors --project ./packages/core

// 处理前
const foo: string = 123 // 类型错误

// 处理后
// @ts-expect-error
const foo: string = 123

# 安装
npm install -D typescript-json-schema

# 生成 JSON Schema
npx typescript-json-schema src/types.ts MyInterface -o schema.json

// input.ts
export interface User {
  /**
   * 用户名，最少3个字符
   * @minimum 3
   */
  username: string

  /**
   * 年龄
   * @minimum 0
   * @maximum 150
   */
  age: number

  /**
   * 邮箱地址
   * @format email
   */
  email: string

  /** 角色 */
  role: "admin" | "user" | "guest"
}

{
  "$ref": "#/definitions/User",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "User": {
      "properties": {
        "username": {
          "description": "用户名，最少3个字符",
          "minLength": 3,
          "type": "string"
        },
        "age": {
          "description": "年龄",
          "maximum": 150,
          "minimum": 0,
          "type": "number"
        },
        "email": {
          "description": "邮箱地址",
          "format": "email",
          "type": "string"
        },
        "role": {
          "description": "角色",
          "enum": ["admin", "user", "guest"],
          "type": "string"
        }
      },
      "required": ["username", "age", "email", "role"],
      "type": "object"
    }
  }
}

# 安装
npm install -D json-schema-to-typescript

# 生成 TypeScript
npx json2ts -i schema.json -o types.ts

// input.json
{
  "title": "User",
  "type": "object",
  "properties": {
    "firstName": { "type": "string" },
    "lastName": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["firstName", "lastName"]
}

export interface User {
  firstName: string
  lastName: string
  age?: number
  tags?: string[]
}

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noEmit": true,
    "incremental": true
  }
}

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "typecheck:watch": "tsc --noEmit --watch"
  }
}

// eslint.config.js（ESLint 9+ flat config）
import js from "@eslint/js"
import ts from "typescript-eslint"

export default ts.config(
  js.configs.recommended,
  ...ts.configs.recommended,
  ...ts.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname
      }
    },
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-misused-promises": "error"
    }
  }
)

npm install type-fest

import type {
  SetRequired,
  SetOptional,
  Merge,
  OmitIndexSignature,
  CamelCase,
  SnakeCase,
  Jsonify,
  PartialDeep,
  ReadonlyDeep
} from "type-fest"

// SetRequired - 将指定属性设为必选
interface User {
  name?: string
  age?: number
  email?: string
}
type RequiredUser = SetRequired<User, "name" | "email">
// { name: string; age?: number; email: string; }

// Merge - 合并两个类型
type Merged = Merge<{ a: string }, { b: number }>
// { a: string; b: number; }

// CamelCase - 转换为驼峰命名
type Camel = CamelCase<"foo-bar-baz">
// 'fooBarBaz'

// Jsonify - 转换为可 JSON 序列化的类型
class User {
  name!: string
  birthDate = new Date()
}
type JsonUser = Jsonify<User>
// { name: string; birthDate: string; }

// PartialDeep - 深层 Partial
interface Config {
  server: {
    host: string
    port: number
  }
}
type PartialConfig = PartialDeep<Config>
// { server?: { host?: string; port?: number; } }

npm install utility-types

import type {
  DeepPartial,
  DeepReadonly,
  DeepRequired,
  PickByValue,
  OmitByValue
} from "utility-types"

// DeepPartial - 深层可选
interface Settings {
  theme: {
    primary: string
    secondary: string
  }
}
type PartialSettings = DeepPartial<Settings>
// { theme?: { primary?: string; secondary?: string; } }

// DeepReadonly - 深层只读
type ReadonlySettings = DeepReadonly<Settings>
// { readonly theme: { readonly primary: string; readonly secondary: string; }; }

// PickByValue - 按值类型选取属性
interface User {
  name: string
  age: number
  email: string
  isActive: boolean
}
type StringProps = PickByValue<User, string>
// { name: string; email: string; }

npm install ts-toolbelt

import type { Object, List, String, Number } from "ts-toolbelt"

// Object 操作
type Update = Object.Update<{ a: 1; b: 2 }, "a", 3>
// { a: 3; b: 2; }

// List 操作
type Take = List.Take<[1, 2, 3, 4, 5], 3>
// [1, 2, 3]

// String 操作
type Split = String.Split<"a-b-c", "-">
// ['a', 'b', 'c']

npm install -D tsd

// src/utils.ts
export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
}

// test/utils.test-d.ts
import { expectType, expectError } from "tsd"
import type { DeepPartial } from "../src/utils"

interface Config {
  name: string
  options: {
    debug: boolean
    timeout: number
  }
}

// 测试类型推断
expectType<DeepPartial<Config>>({
  name: "test"
})

expectType<DeepPartial<Config>>({
  options: {
    debug: true
  }
})

// 测试错误情况
expectError<DeepPartial<Config>>({
  name: 123 // 应该报错
})

{
  "scripts": {
    "test:types": "tsd"
  }
}

npm install -D conditional-type-checks

import { assert, IsExact, IsNullable } from "conditional-type-checks"

type MyType = string | number

// 断言类型相等
assert<IsExact<MyType, string | number>>(true)

// 断言类型可空
assert<IsNullable<string | null>>(true)
assert<IsNullable<string>>(false)

npm install zod

import { z } from "zod"

// 定义 Schema
const UserSchema = z.object({
  username: z.string().min(3, "用户名至少需要 3 个字符"),
  email: z.string().email("无效的邮箱地址"),
  age: z.number().int().positive().optional(),
  role: z.enum(["admin", "user", "guest"]).default("user")
})

// 从 Schema 推断类型
type User = z.infer<typeof UserSchema>
// { username: string; email: string; age?: number; role: 'admin' | 'user' | 'guest' }

// 校验数据
const result = UserSchema.safeParse({
  username: "john",
  email: "john@example.com"
})

if (result.success) {
  console.log(result.data) // 类型安全的访问
} else {
  console.log(result.error.errors) // 详细错误信息
}

// 嵌套对象
const ConfigSchema = z.object({
  server: z.object({
    host: z.string(),
    port: z.number().default(3000)
  }),
  database: z.object({
    url: z.string(),
    pool: z.number().optional()
  })
})

// 联合类型
const ResultSchema = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.string() }),
  z.object({ status: z.literal("error"), error: z.string() })
])

// 异步校验
const AsyncSchema = z.object({
  email: z
    .string()
    .email()
    .refine(
      async (email) => {
        const exists = await checkEmailExists(email)
        return !exists
      },
      { message: "邮箱已存在" }
    )
})

// 变换
const TrimmedString = z.string().trim()
const DateFromString = z.string().transform((val) => new Date(val))

// Next.js API Route
import { z } from "zod"

const RequestSchema = z.object({
  name: z.string(),
  email: z.string().email()
})

export async function POST(request: Request) {
  const body = await request.json()
  const result = RequestSchema.safeParse(body)

  if (!result.success) {
    return Response.json({ errors: result.error.errors }, { status: 400 })
  }

  // result.data 类型安全
  return Response.json({ success: true, data: result.data })
}

npm install class-validator class-transformer

import { IsString, IsEmail, IsInt, Min, Max, validate, validateOrReject } from "class-validator"

export class User {
  @IsString()
  @MinLength(3)
  @MaxLength(20)
  username!: string

  @IsEmail()
  email!: string

  @IsInt()
  @Min(0)
  @Max(150)
  age!: number
}

// 校验实例
const user = new User()
user.username = "jo" // 太短
user.email = "invalid-email"
user.age = -1

const errors = await validate(user)
if (errors.length > 0) {
  console.log("校验失败:", errors)
}

// 或使用 reject 模式
try {
  await validateOrReject(user)
} catch (errors) {
  console.log("校验失败:", errors)
}

import { Controller, Post, Body } from "@nestjs/common"
import { IsString, IsEmail } from "class-validator"

class CreateUserDto {
  @IsString()
  name!: string

  @IsEmail()
  email!: string
}

@Controller("users")
export class UsersController {
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    // 自动校验
    return { success: true }
  }
}

npm install superstruct

import { struct, assert, is } from "superstruct"

// 定义结构
const UserStruct = struct({
  name: "string",
  email: "string",
  age: "number?"
})

// 校验数据
const data = { name: "John", email: "john@example.com" }

if (is(data, UserStruct)) {
  console.log(data.name) // 类型安全
}

// 或使用 assert
try {
  assert(data, UserStruct)
} catch (error) {
  console.log("校验失败:", error)
}

# 安装
npm install -D typescript-coverage-report

# 生成报告
npx typescript-coverage-report

# 指定阈值
npx typescript-coverage-report --threshold 95

# .github/workflows/type-coverage.yml
name: Type Coverage
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx typescript-coverage-report --threshold 95

# 安装
npm install -D typedoc

# 生成文档
npx typedoc src/index.ts

// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "gitRevision": "main",
  "excludePrivate": true,
  "excludeProtected": false,
  "theme": "default"
}

/**
 * 用户服务类
 *
 * @example
 * ```typescript
 * const userService = new UserService();
 * const user = await userService.findById(1);
 * ```
 */
export class UserService {
  /**
   * 根据ID查找用户
   *
   * @param id - 用户ID
   * @returns 用户对象，如果未找到则返回 null
   * @throws {NotFoundError} 当用户不存在时抛出
   *
   * @example
   * ```typescript
   * const user = await userService.findById(1);
   * console.log(user.name);
   * ```
   */
  async findById(id: number): Promise<User | null> {
    // ...
  }
}

# 安装
npm install -D @microsoft/api-extractor

# 初始化配置
npx api-extractor init

# 运行
npx api-extractor run

// api-extractor.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "./dist/index.d.ts",
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
  },
  "apiReport": {
    "enabled": true,
    "reportFolder": "./temp/"
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "./temp/<unscopedPackageName>.api.json"
  }
}

# 安装
npm install -D esbuild

# 直接编译
npx esbuild src/index.ts --bundle --outfile=dist/bundle.js

# 监听模式
npx esbuild src/index.ts --bundle --outfile=dist/bundle.js --watch

# 压缩
npx esbuild src/index.ts --bundle --outfile=dist/bundle.js --minify

import * as esbuild from "esbuild"

// 一次性构建
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outfile: "dist/bundle.js",
  minify: true,
  sourcemap: true,
  platform: "node",
  target: "node18",
  external: ["fs", "path"]
})

// 增量构建
const ctx = await esbuild.context({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outfile: "dist/bundle.js"
})

await ctx.watch()
await ctx.dispose()

# 安装
npm install -D @swc/core @swc/cli

# 编译
npx swc src -d dist

# 监听模式
npx swc src -d dist --watch

// .swcrc
{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true,
      "dynamicImport": true
    },
    "transform": {
      "legacyDecorator": true,
      "decoratorMetadata": true
    },
    "target": "es2020",
    "loose": false,
    "externalHelpers": true
  },
  "module": {
    "type": "es6"
  },
  "minify": {
    "compress": true,
    "mangle": true
  }
}

// Next.js
// next.config.js
module.exports = {
  swcMinify: true
}

// Vite
// vite.config.ts
import { defineConfig } from "vite"

export default defineConfig({
  esbuild: false,
  plugins: [
    {
      name: "swc",
      transform(code, id) {
        if (id.endsWith(".ts") || id.endsWith(".tsx")) {
          return swc.transform(code, {
            jsc: {
              parser: { syntax: "typescript" }
            }
          })
        }
      }
    }
  ]
})

npm install -D fork-ts-checker-webpack-plugin

const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin")

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: "ts-loader",
        options: {
          transpileOnly: true // 跳过类型检查
        }
      }
    ]
  },
  plugins: [
    new ForkTsCheckerWebpackPlugin({
      typescript: {
        diagnosticOptions: {
          semantic: true,
          syntactic: true
        },
        mode: "write-references"
      },
      eslint: {
        files: "./src/**/*.{ts,tsx}"
      }
    })
  ]
}

# 安装
npm install -D tsup

# 打包
npx tsup src/index.ts

# 多入口
npx tsup src/index.ts src/cli.ts

// tsup.config.ts
import { defineConfig } from "tsup"

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["cjs", "esm", "iife"],
  dts: true, // 生成类型声明
  sourcemap: true,
  clean: true,
  minify: true,
  splitting: false,
  external: ["react", "react-dom"],
  treeshake: true,
  outDir: "dist",
  target: "es2020"
})

{
  "name": "my-lib",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "require": "./dist/index.js",
      "import": "./dist/index.mjs",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup"
  }
}

# 安装
npm install -D dts-bundle-generator

# 生成单个 d.ts 文件
npx dts-bundle-generator -o dist/index.d.ts src/index.ts

// dts-config.js
module.exports = {
  entries: [
    {
      filePath: "./src/index.ts",
      outFilePath: "./dist/index.d.ts",
      noCheck: false,
      output: {
        sortNodes: true,
        noBanner: true
      }
    }
  ]
}

┌─────────────────────────────────────────────────────────────┐
│                    工具选型决策树                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  项目类型？                                                  │
│       │                                                     │
│       ├── 前端应用                                          │
│       │       │                                             │
│       │       ├── React/Vue → Vite + zod + type-fest       │
│       │       └── 大型企业应用 → Webpack + ESLint          │
│       │                                                     │
│       ├── 后端服务                                          │
│       │       │                                             │
│       │       ├── NestJS → class-validator + swc           │
│       │       └── Express/Fastify → zod + ts-node-dev      │
│       │                                                     │
│       ├── npm 库                                            │
│       │       │                                             │
│       │       └── tsup + dts-bundle-generator + tsd        │
│       │                                                     │
│       └── Monorepo                                          │
│               │                                             │
│               └── Turborepo + pnpm + 共享 ESLint 配置       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# 需要完整类型检查
npx ts-node script.ts

# 追求速度
npx esno script.ts

// zod - 函数式
const Schema = z.object({ name: z.string() })

// class-validator - 装饰器
class User {
  @IsString() name!: string
}

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

// packages/app/tsconfig.json
{
  "extends": "@my-org/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

// 方案1：安装 @types 包
npm install -D @types/lodash

// 方案2：创建本地声明文件
// src/types/unknown-lib.d.ts
declare module 'unknown-lib' {
  export function doSomething(input: string): number;
}

// 方案3：快速临时方案（不推荐）
import legacy from 'legacy-lib'; // @ts-ignore

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components')
    }
  }
});

// tsconfig.json 同步配置
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "incremental": true, // 增量编译
    "skipLibCheck": true, // 跳过库检查
    "noEmit": true, // 仅类型检查
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

# 使用 swc 替代 tsc 进行代码转换
npx swc src -d dist

# 类型检查单独运行
npx tsc --noEmit

{
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "esbuild": "^0.20.0",
    "zod": "^3.22.0",
    "type-fest": "^4.0.0",
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "prettier": "^3.0.0"
  }
}

{
  "devDependencies": {
    "typescript": "^5.0.0",
    "ts-node-dev": "^2.0.0",
    "swc": "^1.3.0",
    "class-validator": "^0.14.0",
    "class-transformer": "^0.5.0",
    "@typescript-eslint/eslint-plugin": "^7.0.0"
  }
}

{
  "devDependencies": {
    "typescript": "^5.0.0",
    "tsup": "^8.0.0",
    "dts-bundle-generator": "^9.0.0",
    "tsd": "^0.30.0",
    "type-fest": "^4.0.0"
  }
}