TypeScript 配置

库基础配置

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ESNext"],
    "strict": true,
    "strictNullChecks": true,
    "noImplicitOverride": true,
    "noUnusedLocals": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true,
    "isolatedDeclarations": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

关键选项说明

选项	值	说明
`target`	ESNext	现代输出，由打包工具向下兼容
`module`	ESNext	ESM 输出
`moduleResolution`	Bundler	兼容现代打包工具，允许省略扩展名
`strict`	true	尽早捕获错误
`noEmit`	true	由构建工具处理输出
`isolatedDeclarations`	true	更快的 DTS 生成
`verbatimModuleSyntax`	true	要求显式使用 `import type`
`skipLibCheck`	true	加快构建速度

单体仓库配置

根目录 tsconfig.json

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "verbatimModuleSyntax": true
  }
}

子包 tsconfig.json

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "references": [
    { "path": "../utils" }
  ]
}

路径别名

用于单体仓库的内部导入：

{
  "compilerOptions": {
    "paths": {
      "@my-lib/core": ["./packages/core/src"],
      "@my-lib/utils": ["./packages/utils/src"],
      "#internal/*": ["./virtual-shared/*"]
    }
  }
}

Bundler 与 Node 解析模式对比

对由打包工具（Vite、webpack 等）消费的库，使用 Bundler：

允许导入时不加扩展名
支持 package.json 中的 exports 字段
现代、更简单的配置

对仅用于 Node.js 的库，使用 Node16/NodeNext：

需要显式扩展名（.js）
更严格，与 Node.js 行为完全一致

类型声明

让构建工具生成声明文件：

// tsdown.config.ts
export default defineConfig({
  dts: true,                    // 生成 .d.ts
  dts: { resolve: ['@antfu/utils'] }  // 内联特定类型
})

或使用 unbuild：

// build.config.ts
export default defineBuildConfig({
  declaration: 'node16',        // 为 Node.js 兼容性
  declaration: true,            // 为打包工具解析模式
})

常见问题

模块未找到错误

检查 moduleResolution 是否与目标环境匹配：

打包工具："Bundler"
Node.js："Node16" 或 "NodeNext"

类型导入不生效

启用 verbatimModuleSyntax 并使用显式写法：

import type { Foo } from './types'

类型检查缓慢

启用 skipLibCheck: true 和 isolatedDeclarations: true。

3.4 KiB Raw Permalink Blame History Unescape Escape