skillhub-179-ts-library/build/tooling.md

构建工具

工具选择

工具	适用场景
tsdown	大多数库 —— 快速、简单、现代化
unbuild	复杂构建、Nuxt 模块、自动外部化
rollup/rolldown	需要精细控制的大型项目

tsdown（推荐）

pnpm add -D tsdown

基本配置

// tsdown.config.ts
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
})

多入口

export default defineConfig({
  entry: ['src/index.ts', 'src/cli.ts', 'src/utils.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['vue', 'vite'],
})

插件模式（unplugin-*）

export default defineConfig({
  entry: ['src/*.ts'],          // 通配所有入口
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,                // 自动生成 package.json exports
  attw: { profile: 'esm-only' }, // 类型检查配置
})

高级选项

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: {
    resolve: ['@antfu/utils'],  // 在声明文件中内联特定依赖
  },
  external: ['vue'],
  define: {
    __DEV__: 'false',
  },
  hooks: {
    'build:done': async () => {
      // 构建后任务
    },
  },
})

unbuild

pnpm add -D unbuild

基本配置

// build.config.ts
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index'],
  declaration: true,
  rollup: {
    emitCJS: true,
  },
})

带外部化依赖

export default defineBuildConfig({
  entries: ['src/index', 'src/cli'],
  declaration: true,
  externals: ['vue', 'vite'],
  rollup: {
    emitCJS: true,
    inlineDependencies: true,
    dts: { respectExternal: true },
  },
})

输出格式

仅 ESM（现代）

export default defineConfig({
  format: ['esm'],
})

双格式 CJS/ESM（推荐）

export default defineConfig({
  format: ['esm', 'cjs'],
})

带 IIFE 用于 CDN

export default defineConfig([
  { format: ['esm', 'cjs'], dts: true },
  { format: 'iife', globalName: 'MyLib', minify: true },
])

定义标志

常用编译时标志：

export default defineConfig({
  define: {
    __DEV__: `(process.env.NODE_ENV !== 'production')`,
    __TEST__: 'false',
    __BROWSER__: 'true',
    __VERSION__: JSON.stringify(pkg.version),
  },
})

构建脚本

{
  "scripts": {
    "build": "tsdown",
    "dev": "tsdown --watch",
    "prepublishOnly": "pnpm build"
  }
}

故障排除

CJS 默认导出问题

某些打包工具需要显式默认导出：

export default defineConfig({
  hooks: {
    'build:done': async () => {
      // 如有需要，修补 CJS 文件
    },
  },
})

输出中缺少类型声明

确保 dts: true，并检查 tsconfig 中的 isolatedDeclarations。

外部化不生效

检查包是否在 peerDependencies 中，并已在 external 中列出。