AI Skills
tsdown

tsdown

熱門

以 Rolldown 驅動的極速打包工具，用於建置 TypeScript 與 JavaScript 函式庫。適合在開發函式庫、產生型別宣告、打包多種格式，或從 tsup 遷移時使用。

5658星標
314分支
更新於 2026/6/23
獲取技能源代碼

相關技能

tailwind-patterns4.6萬typescript8.1萬web-artifacts-builder15萬
SKILL.md
唯讀
名稱
tsdown
描述

以 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 與 minification 最佳化 bundle
  • 從 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,
})

核心參考

主題 說明 參考
開始使用 安裝、第一個 bundle、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 map 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 exports: true - 產生 exports 欄位 option-package-exports
CSS 處理 [實驗性] css: { ... } — 完整管線，包含預處理器、Lightning CSS、PostCSS、CSS modules、程式碼分割；需安裝 @tsdown/css option-css
CSS modules css: { modules: { localsConvention: 'camelCase' } } — 為 .module.css 檔案提供作用域類別名稱 option-css
CSS inject 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 以獲得最佳 bundle 大小：

    { 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' }

資源