unbuild TypeScript 完全指南：从入门到实战

在当今 JavaScript 和 TypeScript 生态中，项目构建是一项核心任务。开发者常常需要为 Webpack、Rollup 或 esbuild 配置复杂的构建流程。而 unbuild 库提供了一个优雅的解决方案——一个统一的构建系统，将最佳实践和工具整合在单一接口中。它不仅仅是一个构建工具，更是基于 esbuild 和 Rollup 的统一封装，能够自动为你的项目选择最优构建策略。

unbuild 的主要目标是极大简化 TypeScript 库的构建过程。开发者无需花费数小时配置构建文件，即可获得开箱即用的解决方案。该库能自动生成 CommonJS 和 ESM 构建产物、创建类型声明文件（d.ts）、优化打包体积，并支持 TypeScript 的最新特性。这使得 unbuild 成为 npm 包作者和开源项目的理想选择。

unbuild 在以下场景中尤为实用：创建 monorepo 项目、构建支持 tree-shaking 的库、发布包含 TypeScript 源码的包、从旧版构建工具迁移。凭借对 package.json 导出的内置支持以及自动入口点检测，该库让你专注于编写代码，而非配置基础设施。

安装指南

使用 npm（或 yarn、pnpm 等替代工具）安装 unbuild。该库应作为开发依赖安装：

npm install -D unbuild

或使用 yarn：

yarn add -D unbuild

使用 pnpm：

pnpm add -D unbuild

安装后，建议在 package.json 中添加构建脚本：

{
  "scripts": {
    "build": "unbuild",
    "dev": "unbuild --watch"
  }
}

快速上手

创建一个最小可运行的项目。文件结构如下：

my-library/
├── src/
│   └── index.ts
├── package.json
└── tsconfig.json

src/index.ts 内容：

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

export const version = '1.0.0';

tsconfig.json 配置：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

现在运行构建命令：

npx unbuild

执行后，dist 文件夹中将生成以下文件：

dist/index.mjs — ESM 构建产物
dist/index.cjs — CommonJS 构建产物
dist/index.d.ts — 类型声明文件
dist/index.d.mts — ESM 类型声明

unbuild 会自动创建两种构建产物并生成 TypeScript 类型声明。如需在 package.json 中配置导出，请添加：

{
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}