# 构建工具

## 工具选择

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

## tsdown（推荐）

```bash
pnpm add -D tsdown
```

### 基本配置

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

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

### 多入口

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

### 插件模式（unplugin-\*）

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

### 高级选项

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

## unbuild

```bash
pnpm add -D unbuild
```

### 基本配置

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

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

### 带外部化依赖

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

## 输出格式

### 仅 ESM（现代）

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

### 双格式 CJS/ESM（推荐）

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

### 带 IIFE 用于 CDN

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

## 定义标志

常用编译时标志：

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

## 构建脚本

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

## 故障排除

### CJS 默认导出问题

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

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

### 输出中缺少类型声明

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

### 外部化不生效

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