Vant CLI 命令完全指南：dev、build、release、commit-lint 的用法与源码解析

Vant CLI 命令完全指南：dev、build、release、commit-lint 的用法与源码解析

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant

导读

Vant CLI（@vant/cli）是 Vant 移动端组件库配套的命令行工具，为组件库开发者提供了一套开箱即用的工程化能力：本地文档预览、组件库生产构建、文档站点构建、npm 发布以及 commit message 校验。本文以官方文档 commands.zh-CN.md 为主线，逐个讲解内置命令的用法与配置，并结合仓库源码揭示每个命令背后的真实执行链路，帮助你从"会敲命令"进阶到"理解命令"。

命令总览：接入 npm scripts

Vant CLI 内置了一系列命令，最常规的用法是将它们添加到项目的package.json的scripts字段中：

// package.json { "scripts": { "dev": "vant-cli dev", "test": "vant-cli test", "release": "vant-cli release", "build-site": "vant-cli build-site" } }

添加完成后，即可通过npm run dev、npm run release等方式调用。如果不想写入scripts，也可以借助 npm 自带的 npx 直接执行某个命令，无需任何预配置：

npx vant-cli dev

从源码结构看，这些命令统一注册在 cli.ts 中，基于commander实现：每个命令都通过.command()注册，并采用动态import()按需加载对应的实现模块。这意味着vant-cli --version之类的低频命令不会拖慢 dev/build 等高频命令的启动速度。命令的二进制入口由 package.json 中的"bin": { "vant-cli": "./bin.js" }声明，全局安装或通过 pnpm workspace 引用后即可直接使用。

Vant CLI 的命令在执行时会根据项目根目录下的vant.config.mjs定位仓库根路径（ROOT），并由此推导出es、lib、docs、site-dist等关键目录，详见 constant.ts。因此请确保仓库根目录存在vant.config.mjs配置文件。

dev：启动本地开发环境

vant-cli dev用于运行本地开发环境。执行该命令后，Vant CLI 会启动一个本地服务器，用于在开发过程中实时预览组件文档（README）与示例（demo）。

对应的实现非常简单直接，见 dev.ts：

export async function dev() { setNodeEnv('development'); await compileSite(); }

它做了两件事：

1. 通过setNodeEnv('development')将NODE_ENV设为development，让底层编译工具链（Vite/Rsbuild）进入开发模式，支持热更新（HMR）；
2. 调用compileSite()编译文档站点源码（位于site/目录，含桌面端与移动端两套页面），并把组件目录下的README.md与demo/*.vue渲染成可交互的预览页面。

由于走的是标准的本地开发服务器，开发者修改组件源码、demo 或文档后，浏览器页面会即时刷新，整个"文档 + 示例"的开发闭环与组件库本身的迭代天然绑定在一起。

build：构建组件库生产代码

vant-cli build用于构建组件库。运行后会在项目的es和lib两个目录下生成可用于生产环境的组件代码，两者的差异在于模块格式：es面向 ESM（供现代打包器 tree-shaking），lib面向 CommonJS（供 Node 环境与旧工具链）。更详细的目录约定参见 目录结构。

构建流程

从 build.ts 可以看到，build()的整体流程分三步：

export async function build() { setNodeEnv('production'); try { await clean(); await installDependencies(); await runBuildTasks(); } catch (err) { logger.error('Build failed'); // ... 退出码处理 } }

1. clean：调用 clean.ts 中的clean()，并行删除es、lib、dist、site-dist四个目录，确保从干净状态开始构建，避免残留文件污染产物。
2. installDependencies：依据 manager.ts 中getPackageManager()的结果（优先读取vant.config.mjs中build.packageManager的配置，否则探测本机是否有 yarn，回退到 npm）执行install --prod=false，先补齐依赖再编译。
3. runBuildTasks：执行真正的编译任务，包括：剔除demo/、test/等非产物目录的预编译（preCompileDir）、SFC 编译（compileSfc）、脚本按 ESM/CJS 双格式编译（compileScript）、样式编译（compileStyle）、打包入口与样式依赖关系图的生成（genPackageEntry、genStyleDepsMap）等，最终产出es与lib两套代码以及 web-types 等类型辅助文件。

发布 npm 的必要配置

使用build构建完成后，产物位于es与lib目录。发布 npm 包时，需要把以下配置加入到package.json中，npm 才能正确识别包入口并只发布构建产物：

// package.json { "main": "lib/index.js", "module": "es/index.js", "files": ["es", "lib"] }

• main：CommonJS 入口，指向lib/index.js；
• module：ESM 入口，指向es/index.js，现代打包器（Vite、Webpack 等）会优先使用它；
• files：白名单，仅将es、lib打入 npm 包，避免源码、测试、文档等无关文件被意外发布。

build-site：构建文档站点

vant-cli build-site用于构建文档站点，运行后在site目录生成可用于生产环境的文档站点代码。

与dev共享同一套站点编译逻辑，区别在于生产模式与产物目录，见 build-site.ts：

export async function buildSite() { setNodeEnv('production'); await fse.emptyDir(SITE_DIST_DIR); await compileSite(true); }

• 将NODE_ENV设为production，启用压缩、移除开发提示等生产级优化；
• 先清空SITE_DIST_DIR（即site-dist目录），再调用compileSite(true)进行全量编译。

构建完成后，将site-dist目录部署到任意静态文件服务器或 CDN 即可对外提供组件文档站。

release：发布组件库

vant-cli release用于发布组件库。发布前会自动执行build命令，并按照一套完整的流程发布 npm 包，同时处理版本号、git 提交与推送。

支持的参数

在 cli.ts 中，release命令注册了两个可选参数：

vant-cli release [--tag <tag>] [--gitTag]

• --tag <tag>：强制指定 npm 发布标签（如beta、alpha），覆盖默认推断逻辑；
• --gitTag：发布成功后额外生成并推送 git 标签（形如v1.0.0）。

完整执行流程

release.ts 的实现清晰地展示了整个发布链路：

1. 读取当前版本：读取当前目录package.json，打印当前包名与版本号；
2. 交互式输入新版本：通过enquirer弹出输入框，要求开发者填写要发布的新版本号（如1.2.0-beta.1）；
3. 推断 npm tag：getNpmTag(version, forceTag)根据版本号自动推断发布标签——包含beta用beta、包含alpha用alpha、包含rc用rc，否则用latest；传入--tag时强制使用指定标签；
4. 更新版本号：将新版本写回package.json；
5. 自动构建：执行buildPackage，即运行当前包管理器（npm/yarn/pnpm）的run build；如果构建失败，会自动将package.json回滚到之前的版本并抛出错误，避免留下"版本号已改、代码没构建出来"的半发布状态；
6. 发布 npm：执行<packageManager> publish --tag <tag>；当使用 pnpm 时会自动追加--no-git-checks，跳过 pnpm 对 git 状态的检查；
7. 提交代码：执行git add -A && git commit -m "release: <包名> v<版本号>"；若指定了--gitTag，还会创建v<版本号>的 annotated tag；
8. 推送远端：将当前分支与（可选的）tags 推送到origin。

包管理器的选择逻辑同样来自 manager.ts：优先使用vant.config.mjs中build.packageManager的显式配置，未配置时自动探测 yarn，否则回退到 npm。对于 pnpm 工作区（如 Vant 本仓库的 monorepo），推荐在配置中显式指定packageManager，以保证发布命令行为一致。

commit-lint：校验 commit message

vant-cli commit-lint用于校验 commit message 的格式是否符合规范，需要配合husky在提交 commit 时触发。

校验规则

从 commit-lint.ts 的实现可以看到，它读取传入的 git 参数（husky 注入的 commit message 文件路径），用正则commitRE校验，同时放行Merge提交：

const commitRE = /^(revert: )?(fix|feat|docs|perf|test|types|style|build|chore|release|refactor|breaking change)(\(.+\))?: .{1,50}/; const mergeRE = /Merge /;

支持的类型（Allowed Types）包括：

合法的提交格式为类型(可选作用域): 描述，描述长度限制为 1~50 个字符。校验不通过时命令会打印错误信息并process.exit(1)终止提交。

与 husky 集成

在package.json中加入husky的 pre-commit 钩子（以 husky v9 为例）：

// package.json { "scripts": { "prepare": "husky" } }

并在.husky/commit-msg钩子文件中调用：

npx --no -- vant-cli commit-lint $1

这样每次git commit时，husky 都会把 commit message 文件路径作为参数传给vant-cli commit-lint，不符合规范的提交会被当场拦截。这套校验与 changelog 自动生成机制配合：只有符合规范的 message，才能被后续的版本发布流程解析成可读的更新日志，因此官方强烈建议遵守该格式。

附：clean 与底层公共设施

除了文档列出的五个命令，仓库还内置了vant-cli clean命令（cli.ts），用于一键清理所有构建产物目录（es、lib、dist、site-dist），它是build流程中的第一步，也可单独执行以释放磁盘空间或排查构建缓存问题。

理解这些命令后，一条完整的组件库发布链路就清晰了：本地用dev开发调试 → 用build产出es/lib双格式产物并配合main/module/files配置发布 → 用build-site产出并部署文档站点 → 用release一键完成"改版本号 → 构建 → 发 npm → 打 tag → 推送"的全流程，而commit-lint则从提交源头保证每次变更都是规范、可追溯的。

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant