⚡

tsdown库打包工具Skill tsdown

tsdown是一个基于Rolldown和Oxc的快速、优雅的TypeScript和JavaScript库打包工具，用于构建前端库、生成类型声明文件、支持ESM、CJS、IIFE、UMD等多种输出格式，优化打包大小通过树摇和压缩，适用于库构建、项目迁移和前端开发，关键词包括TypeScript打包、JavaScript库构建、快速Bundler、Rolldown工具、tsdown用法。

前端开发 0 次安装 0 次浏览 更新于 3/13/2026

name: tsdown description: 使用由Rolldown驱动的极速打包TypeScript和JavaScript库。在构建库、生成类型声明、打包多种格式或从tsup迁移时使用。

tsdown - 优雅的库打包工具

基于Rolldown和Oxc的快速TypeScript/JavaScript库打包工具。

何时使用

  • 为npm构建TypeScript/JavaScript库
  • 生成TypeScript声明文件(.d.ts)
  • 打包多种格式(ESM、CJS、IIFE、UMD)
  • 通过树摇和压缩优化打包包
  • 以最小更改从tsup迁移
  • 构建React、Vue、Solid或Svelte组件库

快速开始

# 安装
pnpm add -D tsdown

# 基本用法
npx tsdown

# 使用配置文件
npx tsdown --config tsdown.config.ts

# 监视模式
npx tsdown --watch

# 从tsup迁移
npx tsdown-migrate

基本配置

import { defineConfig } from 'tsdown'

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

核心参考

主题 描述 参考
快速开始 安装、首次打包、CLI基础 guide-getting-started
配置文件 配置文件格式、多个配置、工作空间 option-config-file
CLI参考 所有CLI命令和选项 reference-cli
从tsup迁移 迁移指南和兼容性说明 guide-migrate-from-tsup
插件 Rolldown、Rollup、Unplugin支持 advanced-plugins
钩子 自定义逻辑的生命周期钩子 advanced-hooks
编程API 从Node.js脚本构建 advanced-programmatic
Rolldown选项 直接传递选项给Rolldown advanced-rolldown-options
CI环境 CI检测、‘ci-only’ / 'local-only’值 advanced-ci

构建选项

选项 用法 参考
入口点 entry: ['src/*.ts', '!**/*.test.ts'] option-entry
输出格式 format: ['esm', 'cjs', 'iife', 'umd'] option-output-format
输出目录 outDir: 'dist', outExtensions option-output-directory
类型声明 dts: true, dts: { sourcemap, compilerOptions, vue } option-dts
目标环境 target: 'es2020', target: 'esnext' option-target
平台 platform: 'node', platform: 'browser' option-platform
树摇 treeshake: true, 自定义选项 option-tree-shaking
压缩 minify: true, minify: 'dce-only' option-minification
源映射 sourcemap: true, 'inline', 'hidden' option-sourcemap
监视模式 watch: true, 监视选项 option-watch-mode
清理 clean: true, 清理模式 option-cleaning
日志级别 logLevel: 'silent', failOnWarn: 'ci-only' option-log-level

依赖处理

功能 用法 参考
外部依赖 external: ['react', /^@myorg\//] option-dependencies
内联依赖 noExternal: ['dep-to-bundle'] option-dependencies
自动外部化 自动对等/依赖外部化 option-dependencies

输出增强

功能 用法 参考
垫片 shims: true - 添加ESM/CJS兼容性 option-shims
CJS默认 cjsDefault: true (默认) / false option-cjs-default
包导出 exports: true - 自动生成导出字段 option-package-exports
CSS处理 [实验性] 仍在开发中 option-css
非打包模式 unbundle: true - 保留目录结构 option-unbundle
包验证 publint: true, attw: true - 验证包 option-lint

框架和运行时支持

框架 指南 参考
React JSX转换、快速刷新 recipe-react
Vue SFC支持、JSX recipe-vue
WASM 通过rolldown-plugin-wasm的WebAssembly模块 recipe-wasm

常见模式

基础库打包

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

多个入口点

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

浏览器库(IIFE/UMD)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['iife'],
  globalName: 'MyLib',
  platform: 'browser',
  minify: true,
})

React组件库

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['react', 'react-dom'],
  plugins: [
    // React快速刷新支持
  ],
})

保留目录结构

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // 保留文件结构
  format: ['esm'],
  dts: true,
})

CI感知配置

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',
  publint: 'ci-only',
  attw: 'ci-only',
})

WASM支持

import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})

高级钩子

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  hooks: {
    'build:before': async (context) => {
      console.log('构建中...')
    },
    'build:done': async (context) => {
      console.log('构建完成！')
    },
  },
})

配置功能

多个配置

导出数组以支持多个构建配置：

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

条件配置

使用函数进行动态配置：

export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

工作空间/单仓库

使用全局模式构建多个包：

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

CLI快速参考

# 基本命令
tsdown                          # 构建一次
tsdown --watch                  # 监视模式
tsdown --config custom.ts       # 自定义配置
npx tsdown-migrate              # 从tsup迁移

# 输出选项
tsdown --format esm,cjs        # 多种格式
tsdown --outDir lib            # 自定义输出目录
tsdown --minify                # 启用压缩
tsdown --dts                   # 生成声明

# 入口选项
tsdown src/index.ts            # 单个入口
tsdown src/*.ts                # 全局模式
tsdown src/a.ts src/b.ts       # 多个入口

# 开发
tsdown --watch                 # 监视模式
tsdown --sourcemap             # 生成源映射
tsdown --clean                 # 清理输出目录

最佳实践

  1. 始终为TypeScript库生成类型声明：

    { dts: true }

  2. 外部化依赖以避免捆绑不必要代码：

    { external: [/^react/, /^@myorg\//] }

  3. 使用树摇优化打包大小：

    { treeshake: true }

  4. 启用压缩用于生产构建：

    { minify: true }

  5. 添加垫片增强ESM/CJS兼容性：

    { shims: true }  // 添加__dirname、__filename等

  6. 自动生成package.json导出：

    { exports: true }  // 创建正确导出字段

  7. 使用监视模式进行开发：

    tsdown --watch

  8. 保留结构用于多文件工具：

    { unbundle: true }  // 保持目录结构

  9. 在CI中验证包在发布前：

    { publint: 'ci-only', attw: 'ci-only' }

资源