AI Skills
tsdown

tsdown

热门

使用 Rolldown 驱动，以极快速度打包 TypeScript 和 JavaScript 库。适用于构建库、生成类型声明、打包多种格式或从 tsup 迁移。

5658Star
314Fork
更新于 2026/6/23
获取 Skill源代码

相关 Skills

i18n-localization4.4万web-coder3.7万javascript-testing-patterns3.8万
SKILL.md
readonly只读
name
tsdown
description

使用 Rolldown 驱动，以极快速度打包 TypeScript 和 JavaScript 库。适用于构建库、生成类型声明、打包多种格式或从 tsup 迁移。

tsdown - 优雅的库打包工具

基于 Rolldown 和 Oxc 的极速 TypeScript/JavaScript 库打包器。

运行时要求

tsdown 运行需要 Node.js 22.18.0 或更高版本（仅构建时）。但打包后的输出可以通过 target 选项针对更低的 Node.js 版本，因此使用 tsdown 构建的库在运行时并不锁定 Node.js 22+。

如果你的包需要支持 Node.js 18 / 20：

  • 在 CI 中使用 Node.js 22+ 构建（例如设置 target: 'node18' 或 target: 'node20'）。
  • 在你要支持的低版本 Node.js 上测试构建输出（或打包的 tarball）——例如使用矩阵任务在 Node.js 18 / 20 / 22 上运行已发布包的测试。

适用场景

  • 构建用于 npm 的 TypeScript/JavaScript 库
  • 生成 TypeScript 声明文件 (.d.ts)
  • 打包为多种格式（ESM、CJS、IIFE、UMD）
  • 通过 tree shaking 和压缩优化包体积
  • 从 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

如需完整的选项映射迁移帮助，请安装专用的 tsdown-migrate 技能：npx skills add rolldown/tsdown --skill tsdown-migrate
| 钩子 | 用于自定义逻辑的生命周期钩子 | 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
Tree shaking treeshake: true, 自定义选项 option-tree-shaking
压缩 minify: true, minify: 'dce-only' option-minification
Source maps sourcemap: true, 'inline', 'hidden' option-sourcemap
监听模式 watch: true, 监听选项 option-watch-mode
清理 clean: true, 清理模式 option-cleaning
日志级别 logLevel: 'silent', failOnWarn: false option-log-level

依赖处理

功能 用法 参考
从不打包 deps: { neverBundle: ['react', /^@myorg\//] } option-dependencies
始终打包 deps: { alwaysBundle: ['dep-to-bundle'] } option-dependencies
仅打包 deps: { onlyBundle: ['cac', 'bumpp'] } - 白名单 option-dependencies
跳过 node_modules deps: { skipNodeModulesBundle: true } option-dependencies
自动外部化 自动将依赖/对等依赖/可选依赖外部化 option-dependencies

输出增强

功能 用法 参考
Shims shims: true - 添加 ESM/CJS 兼容性 option-shims
CJS 默认 cjsDefault: true (默认) / false option-cjs-default
包导出 exports: true - 生成 exports 字段 option-package-exports
CSS 处理 [实验性] css: { ... } — 完整的管道，支持预处理器、Lightning CSS、PostCSS、CSS 模块、代码分割；需要 @tsdown/css option-css
CSS 模块 css: { modules: { localsConvention: 'camelCase' } } — 为 .module.css 文件生成作用域类名 option-css
CSS 注入 css: { inject: true } — 在 JS 输出中保留 CSS 导入 option-css
非打包模式 unbundle: true - 保留目录结构 option-unbundle
根目录 root: 'src' - 控制输出目录映射 option-root
可执行文件 [实验性] exe: true - 打包为独立可执行文件，通过 @tsdown/exe 跨平台支持 option-exe
包验证 publint: true, attw: true - 验证包 option-lint

框架与运行时支持

框架 指南 参考
React JSX 转换、React Compiler recipe-react
Vue SFC 支持、JSX recipe-vue
Solid SolidJS JSX 转换 recipe-solid
Svelte Svelte 组件库（推荐源码分发） recipe-svelte
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,
  deps: {
    neverBundle: ['react', 'react-dom'],
  },
  inputOptions: {
    jsx: { runtime: 'automatic' },
  },
})

保留目录结构

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',  // 选择加入：在 CI 中警告视为错误
  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()],
})

带 CSS 和 Sass 的库

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  target: 'chrome100',
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "src/styles/variables" as *;`,
      },
    },
  },
})

独立可执行文件

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: true,
})

跨平台可执行文件（需要 @tsdown/exe）

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    targets: [
      { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },
      { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },
      { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },
    ],
  },
})

带钩子的高级用法

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,
  }
})

工作区/Monorepo

使用 glob 模式构建多个包：

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 -d lib                  # 自定义输出目录 (--out-dir)
tsdown --minify                # 启用压缩
tsdown --dts                   # 生成声明
tsdown --exe                   # 打包为独立可执行文件
tsdown --unbundle              # 非打包模式

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

# 工作区 / Monorepo
tsdown -W                      # 启用工作区模式
tsdown -W -F my-package        # 过滤特定包
tsdown --filter /^pkg-/        # 按正则过滤

# 开发
tsdown --watch                 # 监听模式
tsdown --sourcemap             # 生成 source map
tsdown --clean                 # 清理输出目录
tsdown --from-vite             # 复用 Vite 配置
tsdown --tsconfig tsconfig.build.json  # 自定义 tsconfig

最佳实践

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

    { dts: true }

  2. 外部化依赖以避免打包不必要的代码：

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

  3. 使用 tree shaking 以获得最佳包体积：

    { treeshake: true }

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

    { minify: true }

  5. 添加 shims 以获得更好的 ESM/CJS 兼容性：

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

  6. 自动生成 package.json 的 exports 字段：

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

  7. 开发时使用监听模式：

    tsdown --watch

  8. 对于包含大量文件的工具库，保留目录结构：

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

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

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

资源