基于VSCode的Node环境配合Tsup实现零配置TypeScript库构建-VSCode-PHP中文网

tsup更适合库构建，因其内置typescript编译、esbuild打包、自动处理重导出的.d.ts生成、多格式输出及默认tree shaking，避免tsc+rollup的配置耦合与类型声明缺陷。

基于vscode的node环境配合tsup实现零配置typescript库构建

tsup 能替代 tsc + rollup 组合，但「零配置」只在默认场景成立；真实项目几乎必然要改 tsup.config.ts 或传参控制输出格式、入口、dts 生成等。

为什么 tsup 比 tsc + rollup 更适合库构建

tsup 内部封装了 TypeScript 编译、ESBuild 打包、类型声明生成（--dts）、多格式输出（cjs/esm）等流程，避免手动配 rollup.config.js 和 tsconfig.json 的耦合冲突。比如 tsc --declaration 生成的 .d.ts 不带重导出路径，而 tsup 的 --dts 会自动处理 index.ts 中的 export * from './xxx'，生成扁平、可用的类型文件。

常见错误现象：tsc 编译后 node_modules 里没类型、import 提示 “cannot find module” 或 “has no exported member”，往往是因为没正确生成/合并声明文件 —— tsup 默认就解决这个。

tsup 默认启用 tree-shaking，tsc 不做此优化
tsup 输出体积通常比 tsc + rollup 小 10–30%，因 ESBuild 编译更快、更激进
不支持 incremental 编译（tsc --watch 那种），开发时需搭配 tsup --watch，但热更粒度是整个包，不是单文件

`tsup` 的最小可行配置长什么样

多数库只需一个 package.json 脚本，无需任何配置文件：

npm install tsup --save-dev

然后在 package.json 里加：

"scripts": {
  "build": "tsup src/index.ts --format cjs,esm --dts"
}

运行 npm run build 后，会输出：

用于自动切换项目中适合的node 版本

根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。

下载

dist/index.js（CommonJS）
dist/index.mjs（ESM）
dist/index.d.ts（合并后的类型声明）

注意：--format cjs,esm 必须显式指定，否则只输出 cjs；--dts 不加就不会生成 .d.ts，哪怕你写了 declare module 也没用。

必须改配置的三个典型场景

一旦项目含以下任一需求，就得建 tsup.config.ts 或加 CLI 参数：

需要保留 process.env.NODE_ENV 注入：默认会被 esbuild 移除，得加 --define NODE_ENV=development 或在 config 里写 define: { NODE_ENV: '"development"' }
入口不止一个文件：比如 src/index.ts + src/cli.ts，得用 entry: ['src/index.ts', 'src/cli.ts']，并配合 outDir: 'dist' 控制输出结构
要生成 .d.ts 但排除某些内部模块：默认全量提取，容易把 __tests__ 或 utils/internal.ts 也打进类型文件，此时需 dts: { only: true } + include: ['src/index.ts']

示例 tsup.config.ts：

import { defineConfig } from 'tsup';
<p>export default defineConfig({
entry: ['src/index.ts'],
format: ['cjs', 'esm'],
dts: true,
outDir: 'dist',
clean: true,
sourcemap: true,
});</p>

VSCode 调试时如何让断点落到 TS 源码而非 JS

tsup 默认不生成 .map 文件，或生成但路径不对，导致 VSCode 断点失效。必须显式开启且确保 sourceRoot 正确：

加参数 --sourcemap（CLI）或配置 sourcemap: true（config）
确认 tsup 版本 ≥ 7.2.0，旧版 sourcemap 路径写死为 ../src，实际项目结构不符
VSCode 的 launch.json 中，sourceMaps 设为 true，outFiles 指向 dist/**/*.js，不要漏掉 **/*.mjs

如果仍跳不到 TS 行，检查 dist/index.js.map 里的 sources 字段是否为 ["../src/index.ts"] —— 若是 ["src/index.ts"]，说明构建时工作目录不对，需在 package.json 脚本中加 cd src && tsup ... 或统一用 cwd 配置。

真正麻烦的不是跑起来，而是当你要发布一个带 ESM + 类型 + 环境变量 + 多入口的库时，tsup 的「零配置」假象瞬间破灭 —— 它只是把配置从 3 个文件压缩成 1 个，但该填的坑一个没少。