如何快速用 vp pack 打包可发布 npm 库:Vite+ 多格式与 dts 一键构建实战指南
如何快速用 vp pack 打包可发布 npm 库:Vite+ 多格式与 dts 一键构建实战指南
Vite+(Vite Plus) 是面向 Web 开发的统一工具链,它的 vp pack 子命令可以一键构建可发布到 npm 的 TypeScript 库:自动打包、生成 .d.ts 类型声明、输出 ESM/CJS 等多种格式,开箱即用、零额外依赖。对于新手来说,这是把库发布流程从"半天折腾"缩短到"一条命令"的最快路径。
为什么选 vp pack?一个工具搞定所有
过去构建一个 npm 库,往往要同时管理 Rollup、TypeScript 编译器、Bundler 等多个工具及其配置文件,版本对齐就够喝一壶的。Vite+ 的思路是把整个 Web 工具链收敛到一个入口:dev server、测试、lint、构建、打包,全部通过 vp 命令族完成,且共享同一个 vite.config.ts 配置文件。
vp pack 底层基于 tsdown(Rolldown 驱动的打包器),它内置了库构建所需的一切能力:
- ✅ dts 生成:一键产出类型声明文件,消费方 IDE 提示直接可用
- ✅ 多格式输出:
esm、cjs、iife、umd任选 - ✅ Source Map、Tree Shaking、Minify:生产级优化默认就绪
- ✅ CSS 打包:CSS Modules、Lightning CSS 优化开箱即用
- ✅ 缓存加速:通过
vp run调用可命中构建缓存,重复构建接近零耗时
快速上手:一条命令构建你的第一个库
假设你的项目里有一个入口文件 src/index.ts,在项目根目录直接执行:
vp pack src/index.ts
输出如下,产物写入 dist/index.mjs,并附带体积报告:
ℹ entry: src/index.ts
ℹ Build start
ℹ dist/index.mjs 1.2 kB │ gzip: 0.4 kB
ℹ 1 files, total: 1.2 kB
✔ Build complete in 312ms
💡 如果还没写入口文件,
vp pack会友好地提示你:error: No input files, try "vp pack <your-file>" or create src/index.ts
构建完成后的完整效果(含缓存命中场景),可参考测试快照 command_pack.md。
常用参数速查表:dts、多格式与 watch 模式
vp pack 支持通过命令行参数灵活控制构建行为,新手最常用的几个如下:
| 参数 | 作用 | 默认值 |
|---|---|---|
--dts |
生成 .d.ts 类型声明文件 |
关 |
-f, --format <format> |
输出格式:esm / cjs / iife / umd |
esm |
-d, --out-dir <dir> |
产物输出目录 | dist |
--sourcemap |
生成 Source Map | 关 |
--minify |
压缩产物 | 关 |
--platform <platform> |
目标平台:node / browser / neutral |
node |
-w, --watch |
监听文件变化,增量重构建 | 关 |
--publint / --attw |
发布前质量检查 | 关 |
-W, --workspace |
启用 monorepo 工作区模式 | 关 |
一个典型的多格式 + 类型声明构建命令:
vp pack src/index.ts --format esm --format cjs --dts --sourcemap
配置写法:把 pack 配置放进 vite.config.ts
推荐把打包配置统一写在 vite.config.ts 的 pack 块中,而不是单独维护 tsdown.config.ts——这样所有工具配置集中一处,维护心智负担更低:
import { defineConfig } from 'vite-plus';
export default defineConfig({
pack: {
dts: true,
format: ['esm', 'cjs'],
sourcemap: true,
},
});
配好之后,项目里任意位置只需执行裸命令 vp pack,就会自动按配置构建。更完整的参数与选项说明见官方配置文档 pack config。
进阶玩法:watch 模式、构建缓存与可执行文件
1)watch 模式 + 成功钩子:开发期监听文件变化,构建成功后立即执行命令(比如运行产物验证):
vp pack src/index.ts --watch --on-success 'node dist/index.mjs'
2)构建缓存:把 vp pack 声明为 vp run 任务后,重复执行会直接命中缓存、回放上次结果:
$ vp pack src/index.ts ◉ cache hit, replaying
✔ Build complete
---
vp run: cache hit, 286ms saved.
3)独立可执行文件(实验性):借助 Node.js Single Executable Applications,可以把 CLI 工具打包成不依赖 Node.js 环境的原生可执行文件,只需在配置中开启 exe: true。该能力已内置于 Vite+,无需单独安装 @tsdown/exe,要求 Node.js 25.7.0+。
4)CSS 打包:vp pack 默认支持转换并打包 CSS(含 CSS Modules 与 Lightning CSS 优化),同样无需额外安装依赖。
以上进阶能力的详细说明见官方指南 guide/pack。
Monorepo 场景:一次构建多个包
在 pnpm workspace 等 monorepo 中,可以用工作区模式一次构建多个库,并用 --filter 精确筛选目标包:
vp pack --workspace --filter my-lib
也可以从仓库根目录直接构建某个成员包:vp run hello#build。实际效果参考 monorepo 测试快照 command_pack_monorepo.md。
总结与延伸阅读
vp pack 把"构建可发布 npm 库"这件繁琐的事简化成了:配置放 vite.config.ts,命令敲 vp pack,dts 和多格式输出自动搞定。配合 --publint、--attw 等质量检查参数,还能在发布前替你把关包结构与类型正确性。
更多学习资源:
- 📘 官方指南:docs/guide/pack.md
- 📘 官方配置文档:docs/config/pack.md
- 📜 命令设计 RFC:rfcs/pack-command.md
- 🔍 命令行帮助快照:command_pack.md
- 📦 CLI 打包实现:packages/cli/
动手试试吧,一条 vp pack,你的库离 npm 只差一次 npm publish。🚀

