如何快速用 vp pack 打包可发布 npm 库:Vite+ 多格式与 dts 一键构建实战指南

原创2026-10-10 17:41:271,411 阅读
文章标签:开发工具构建工具CLI前端构建代码质量Lint测试Monorepo前端

如何快速用 vp pack 打包可发布 npm 库:Vite+ 多格式与 dts 一键构建实战指南

Vite+(Vite Plus) 是面向 Web 开发的统一工具链,它的 vp pack 子命令可以一键构建可发布到 npm 的 TypeScript 库:自动打包、生成 .d.ts 类型声明、输出 ESM/CJS 等多种格式,开箱即用、零额外依赖。对于新手来说,这是把库发布流程从"半天折腾"缩短到"一条命令"的最快路径。

Vite+ 统一工具链封面图,展示 Vite+ 项目标识

为什么选 vp pack?一个工具搞定所有

过去构建一个 npm 库,往往要同时管理 Rollup、TypeScript 编译器、Bundler 等多个工具及其配置文件,版本对齐就够喝一壶的。Vite+ 的思路是把整个 Web 工具链收敛到一个入口:dev server、测试、lint、构建、打包,全部通过 vp 命令族完成,且共享同一个 vite.config.ts 配置文件。

Vite+ 生态集成图,展示 Vite+ 与 Nuxt、Svelte、React、Solid、Astro、Vue 等框架的连接关系

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 等质量检查参数,还能在发布前替你把关包结构与类型正确性。

更多学习资源:

动手试试吧,一条 vp pack,你的库离 npm 只差一次 npm publish。🚀

登录后查看全文
vite-plus