tsdown 快速上手实操：零配置也能跑的TS极速构建工具

一、tsdown的实用优势

1. 极速构建：底层是esbuild，比传统tsc编译快几倍，大项目也能秒级构建；
2. 零配置友好：配置文件可以空内容，默认规则能覆盖80%的TS项目需求；
3. 功能全且实用：多格式输出、自动生成d.ts、代码压缩、模式、树摇这些开发必备功能都有；
4. 上手成本低：单配置文件+简洁配置项，不用同时学多个工具的语法，新手也能一次配好。

特别适合做TS工具库、NPM包、Node小模块，轻量又高效。

二、项目初始化 & 依赖安装

新建项目文件夹，执行以下命令，两步搞定初始化，依赖只装必要的：

# 快速初始化package.json，一路默认回车
npm init -y
# 安装tsdown开发依赖
npm i -D tsdown
# 【可选】如果需要生成.d.ts类型声明文件，安装typescript（发布NPM包建议装）
npm i -D typescript

三、标准化项目文件结构

搭一个通用的TS项目结构，清晰易维护，构建产物会自动生成到dist目录，不用手动创建：

├── dist/               # 构建后自动生成（产物、类型声明、sourcemap）
├── src/
│   ├── index.ts        # 项目入口（统一导出所有模块）
│   └── tools.ts        # 业务工具函数（示例代码）
├── package.json        # 项目信息 + 构建脚本
└── tsdown.config.ts    # tsdown配置文件（可空，支持自定义）

四、编写示例代码

替换成日常开发中常用的工具函数，带完整TS类型注解，简单实用，方便后续验证构建效果。

src/tools.ts - 工具函数模块

写两个高频用到的小工具，加了简单注释，符合TS开发规范：

/**
 * 精准判断数据类型
 * @param val 任意值
 * @returns 小写类型名（如string、array、null）
 */
export function getType(val: any): string {
  return Object.prototype.toString.call(val).slice(8, -1).toLowerCase()
}

/**
 * 数组去重（支持数字/字符串数组）
 * @param arr 待去重数组
 * @returns 去重后的新数组
 */
export function uniqueArr<T extends number | string>(arr: T[]): T[] {
  return [...new Set(arr)]
}

src/index.ts - 项目统一入口

作为对外暴露的唯一入口，按需导出工具函数，外部引用时只需要导入这个文件就行，符合模块化开发习惯：

// 统一导出，对外提供清晰的API
export { getType, uniqueArr } from './tools'

五、tsdown.config.ts 配置：空配置可用 + 特殊属性全解

这是核心部分，tsdown支持配置文件空内容直接运行（用默认配置），也能根据需求加自定义配置和特殊属性。下面提供两个模板，按需选择，都带TS类型提示。

模板1：最简空配置（推荐小项目/快速开发）

配置文件里什么都不用写，直接导出空配置，tsdown会自动启用内置默认配置，开箱即用，省时间：

import { defineConfig } from 'tsdown'

// 空配置：直接用默认规则，无需手动配置任何项
export default defineConfig({})

模板2：完整配置（含特殊属性，推荐生产/大项目/NPM包）

保留所有核心配置项，重点标注特殊属性（日常易忽略、生产常用），每一项都加了实用注释，可根据自己的项目场景修改，直接替换上面的空配置就行：

import { defineConfig } from 'tsdown'

export default defineConfig({
  // 基础入口输出配置
  entry: ['./src/index.ts'], // 入口：单入口写字符串，多入口写数组，空配置默认识别src/index.ts
  outDir: './dist',          // 输出目录，默认就是./dist
  target: 'es6',             // 语法降级，es6兼容大部分现代环境，需要兼容低版本可设为es5
  format: 'esm',             // 输出格式：esm/cjs/iife，可写数组同时输出多格式（如['esm', 'cjs']）
  platform: 'neutral',       // 运行平台：node（Node环境）/browser（浏览器）/neutral（通用）

  // 优化相关配置
  clean: true,        // 构建前清空dist，建议开启，避免旧产物残留
  dts: true,          // 生成.d.ts类型声明，需提前装typescript，发布NPM包必开
  sourcemap: true,    // 生成源码映射，方便调试，生产环境可设为false减小体积
  treeshake: true,    // 树摇：自动删除未使用代码，默认开启，不用手动关
  minify: true,       // 代码压缩，生产开、开发关（开发关了方便看编译后的代码）

  // 开发调试配置
  watch: false,       // 模式：开发开，文件修改自动重新构建，生产关

  // 特殊属性（重点）：日常开发易忽略，按需使用
  unbundle: false,    // 拆包：多入口项目开，按入口拆分产物；单入口关了就行
  external: [],       // 外部依赖：指定不打包进产物的包（如react/vue），需外部自行引入
  noExternal: []      // 强制打包：覆盖external，即使在external里也强制打包进产物
})

关键特殊属性实用说明

不用死记，知道这些场景怎么用就行：

• clean：必开，否则每次构建的新产物会和旧产物混在一起，容易出问题；
• dts：发布NPM包必开，否则其他TS项目引用时没有类型提示；
• external/noExternal：开发基于React/Vue的工具库时用，不让核心库打包进产物，减小体积；
• unbundle：只有多入口项目需要开，单入口开了反而会生成多余文件；
• minify：开发阶段建议设为false，编译后的代码有格式，方便调试问题。

六、配置package.json 构建脚本

添加两个常用脚本，符合前端开发的使用习惯，一行命令就能构建/开发，空配置和完整配置都能适配：

{
  "name": "tsdown-demo",
  "version": "1.0.0",
  "type": "module", // 输出esm格式建议加，符合Node的ES模块规范，输出cjs可删除
  "main": "./dist/index.js", // 产物主入口，NPM包必备
  "types": "./dist/index.d.ts", // 类型声明入口，开dts时必配
  "scripts": {
    "build": "tsdown", // 生产构建：一次性打包所有产物
    "dev": "tsdown --watch" // 开发模式：文件变化，自动重新构建
  },
  "devDependencies": {
    "tsdown": "^latest",
    "typescript": "^5.5.4" // 开dts时必须装，没开可以删
  }
}

七、执行构建 & 验证结果

配置全部搞定后，执行简单命令就能构建，不管是空配置还是完整配置，步骤都一样：

# 生产环境构建（生成压缩后的产物，适合发布/部署）
npm run build
# 开发环境构建（文件变化，自动更新，适合写代码时用）
npm run dev

构建产物说明

执行npm run build后，dist目录会自动生成对应的产物文件，以开dts/sourcemap/minify为例，产物如下，可直接用于NPM包发布或其他项目引用：

dist/
├── index.js        # 编译+压缩后的JS核心产物
├── index.d.ts      # 自动生成的类型声明文件（TS项目引用有提示）
└── index.js.map    # 源码映射文件（方便调试）

快速验证构建是否成功

在dist目录下新建test.js，引入构建后的产物，执行命令看输出，验证功能是否正常：

import { getType, uniqueArr } from './index.js'

// 测试工具函数
console.log(getType('tsdown 实操')); // 输出：string
console.log(getType([1,2,3]));      // 输出：array
console.log(uniqueArr([1,1,2,3,3]));// 输出：[1,2,3]

执行以下命令，控制台正常输出结果，说明构建完全成功：

node dist/test.js

八、核心配置项速查

整理了日常开发最常用的配置项、作用和默认值，贴在这方便开发时快速查阅，不用每次翻文档：