一、引言如果你曾用TypeScript编写过一个npm包一定经历过这样的纠结用tsc只能输出JS无法打包用Rollup配置复杂光是让TypeScript、CommonJS和ES Module和平共处就要折腾半天用Webpack又太重杀鸡用牛刀。2025年如果你去问一个开源库作者“TypeScript库用什么打包”十有八九会得到一个答案——tsup。这个由EGOIST开发的打包工具基于esbuild构建以“零配置、极速构建、多格式输出”著称周下载量超过270万。从shadcn/ui到React-Redux从Turborepo示例项目到无数个人开源库tsup已成为TypeScript库打包的事实标准。二、tsup是什么tsup是一个基于esbuild的TypeScript库打包工具官方定位是“最简单、最快的TypeScript库打包方式”。2.1 它解决了什么问题写一个TypeScript npm包通常面临三个核心需求TS转译把.ts/.tsx源码转成JavaScript双模式兼容同时输出ESMES Module和CJSCommonJS两种格式让用户无论用import还是require都能使用类型声明生成输出.d.ts文件提供TypeScript类型支持传统方案需要组合使用tsc、Rollup、rollup-plugin-dts等多个工具配置繁琐且容易出错。tsup的价值就在于——一个工具、一条命令、一次搞定。三、核心特性3.1 零配置开箱即用tsup最核心的设计理念是“no config”——提供合理的默认值让大多数TypeScript库项目无需配置文件即可工作。最简单的用法只有一条命令tsup src/index.ts这条命令自动完成TypeScript/JavaScript打包、输出到./dist目录、自动排除node_modules依赖。3.2 极速构建tsup底层基于esbuild——一个用Go语言编写的打包器构建速度比传统工具Webpack、Rollup快10-100倍。速度差异在大型项目中尤为明显。一个中等规模的TypeScript库tsc编译可能需要几秒而tsup通常在毫秒级完成。这种速度优势让开发时的“修改→构建→测试”循环几乎无感。3.3 多格式输出tsup可以在一次构建中同时生成多种模块格式格式扩展名适用场景cjs.js/.cjsNode.js CommonJSesm.mjs/.js现代ES Module环境iife.global.js浏览器全局变量这意味着你只需要一次配置就能同时兼容所有主流使用场景。3.4 智能依赖外置tsup会自动将package.json中的dependencies和peerDependencies标记为外部依赖避免将node_modules打包进库中——这对Node.js库来说通常是正确做法。3.5 双引擎策略tsup采用了一个精妙的设计用esbuild打包JavaScript用Rollup打包类型声明。esbuild负责JS极速构建、原生TS支持、内置压缩和Tree-shakingRollup负责.d.ts将分散的类型声明文件合并为单一入口处理复杂的类型依赖关系这种“各取所长”的策略让tsup在速度和正确性之间取得了最佳平衡。3.6 TypeScript类型声明生成通过--dts参数tsup可以自动生成合并后的.d.ts类型声明文件tsup src/index.ts--dts输出产物中会包含index.d.ts用户安装你的包后即可获得完整的TypeScript类型支持。四、实际应用场景4.1 主要适用场景tsup最擅长的场景是TypeScript npm包的构建具体包括纯JS/TS工具库如lodash、dayjs这类通用工具函数库React/Vue组件库需要同时输出ESM和CJS并保留类型声明CLI工具支持Shebang自动添加#!/usr/bin/env nodeMonorepo中的共享包与Turborepo等工具配合实现高效的包间构建4.2 shadcn/ui开源组件库的标杆案例shadcn/ui是当前最流行的React组件库之一其构建工具正是tsup。通过tsupshadcn/ui实现了同时输出ESM和CJS两种格式完整的TypeScript类型支持极快的构建速度保障了频繁发布的效率4.3 React-Redux大型项目的构建优化React-Redux作为Redux官方的React绑定库其构建配置直接影响了数百万项目的开发体验。React-Redux团队选择tsup作为构建工具实现了环境分离打包通过NODE_ENV区分开发和生产环境生成不同产物多格式输出同时输出CJS和ESM格式按需加载优化利用tsup的Tree-shaking能力4.4 个人组件库与设计系统无数个人开发者和团队使用tsup构建自己的组件库和设计系统。一个典型的配置会将react、antd等运行时依赖标记为peerDependencies并通过--external排除同时生成ESM、CJS和.d.ts类型声明利用watch模式实现开发时的实时构建4.5 Monorepo中的共享包在Turborepo等Monorepo方案中tsup常被用于构建各个共享包。配合--watch模式可以实现“修改共享包→自动重新构建→上层应用热更新”的流畅开发体验。五、开发实践指南5.1 安装在项目根目录执行npminstalltsup-D# 或yarnaddtsup--dev# 或pnpmaddtsup-D5.2 基础配置创建tsup.config.ts配置文件import{defineConfig}fromtsupexportdefaultdefineConfig({entry:[src/index.ts],// 入口文件format:[esm,cjs],// 同时输出ESM和CJSdts:true,// 生成类型声明文件sourcemap:true,// 生成sourcemapclean:true,// 构建前清空dist目录minify:false,// 开发环境不压缩splitting:false,// 库打包不需要代码分割target:es2020,// 转译目标})5.3 在package.json中配置脚本{scripts:{build:tsup,dev:tsup --watch,prepublishOnly:npm run build}}5.4 React组件库的典型配置对于React组件库需要将React等运行时依赖排除import{defineConfig}fromtsupexportdefaultdefineConfig({entry:[src/index.ts],format:[esm,cjs],dts:true,external:[react,react-dom],sourcemap:true,clean:true,})5.5 CLI工具的配置如果构建的是命令行工具需要开启shebang选项exportdefaultdefineConfig({entry:[src/cli.ts],format:[cjs],shebang:true,// 自动添加 #!/usr/bin/env nodedts:true,})5.6 实践建议类型检查与构建分离tsup默认不做类型检查为了速度建议在CI或pre-commit中单独运行tsc --noEmit。善用watch模式开发时使用tsup --watch修改源码后自动重新构建。按需使用minify库代码通常不需要压缩交给应用层做保持可读性更有利于调试。注意CSS支持tsup的CSS支持仍处于实验阶段复杂样式方案建议配合其他工具。六、与其他工具的对比工具优势适用场景tsup零配置、极速、双格式输出、类型声明大多数TypeScript库tsdownRolldown引擎、更快、更低内存新项目、Vite生态Rollup最强Tree-shaking、插件生态丰富复杂构建需求unbuildRollup底层、Nuxt生态Nuxt/UnJS项目esbuild最底层的极速引擎需要完全自定义的场景tsup是目前最主流、最成熟的选择周下载量达270万。tsdown作为新兴工具值得关注但对现有tsup项目无需急于迁移。七、总结tsup之所以能成为TypeScript库打包的“默认答案”核心在于它精准地解决了库作者的三个核心痛点配置复杂→ 零配置开箱即用构建太慢→ 基于esbuild毫秒级构建格式兼容→ 一次构建同时输出ESM、CJS、类型声明它不试图做所有事而是把TypeScript库打包这件事做到极致。无论你是在开发一个开源工具库、一个React组件库还是一个CLI工具tsup都能让你把精力放在写代码上而不是配置构建工具上。正如社区所言“tsup wraps esbuild with library defaults, while raw esbuild leaves declaration files and package output conventions to you.”——tsup就是那个帮你搞定所有“约定俗成”的打包工具。
