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 CLIvant/cli是 Vant 移动端组件库配套的命令行工具为组件库开发者提供了一套开箱即用的工程化能力本地文档预览、组件库生产构建、文档站点构建、npm 发布以及 commit message 校验。本文以官方文档 commands.zh-CN.md 为主线逐个讲解内置命令的用法与配置并结合仓库源码揭示每个命令背后的真实执行链路帮助你从会敲命令进阶到理解命令。命令总览接入 npm scriptsVant 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.tsexport async function dev() { setNodeEnv(development); await compileSite(); }它做了两件事通过setNodeEnv(development)将NODE_ENV设为development让底层编译工具链Vite/Rsbuild进入开发模式支持热更新HMR调用compileSite()编译文档站点源码位于site/目录含桌面端与移动端两套页面并把组件目录下的README.md与demo/*.vue渲染成可交互的预览页面。由于走的是标准的本地开发服务器开发者修改组件源码、demo 或文档后浏览器页面会即时刷新整个文档 示例的开发闭环与组件库本身的迭代天然绑定在一起。build构建组件库生产代码vant-cli build用于构建组件库。运行后会在项目的es和lib两个目录下生成可用于生产环境的组件代码两者的差异在于模块格式es面向 ESM供现代打包器 tree-shakinglib面向 CommonJS供 Node 环境与旧工具链。更详细的目录约定参见 目录结构。构建流程从 build.ts 可以看到build()的整体流程分三步export async function build() { setNodeEnv(production); try { await clean(); await installDependencies(); await runBuildTasks(); } catch (err) { logger.error(Build failed); // ... 退出码处理 } }clean调用 clean.ts 中的clean()并行删除es、lib、dist、site-dist四个目录确保从干净状态开始构建避免残留文件污染产物。installDependencies依据 manager.ts 中getPackageManager()的结果优先读取vant.config.mjs中build.packageManager的配置否则探测本机是否有 yarn回退到 npm执行install --prodfalse先补齐依赖再编译。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] }mainCommonJS 入口指向lib/index.jsmoduleESM 入口指向es/index.js现代打包器Vite、Webpack 等会优先使用它files白名单仅将es、lib打入 npm 包避免源码、测试、文档等无关文件被意外发布。build-site构建文档站点vant-cli build-site用于构建文档站点运行后在site目录生成可用于生产环境的文档站点代码。与dev共享同一套站点编译逻辑区别在于生产模式与产物目录见 build-site.tsexport 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 的实现清晰地展示了整个发布链路读取当前版本读取当前目录package.json打印当前包名与版本号交互式输入新版本通过enquirer弹出输入框要求开发者填写要发布的新版本号如1.2.0-beta.1推断 npm taggetNpmTag(version, forceTag)根据版本号自动推断发布标签——包含beta用beta、包含alpha用alpha、包含rc用rc否则用latest传入--tag时强制使用指定标签更新版本号将新版本写回package.json自动构建执行buildPackage即运行当前包管理器npm/yarn/pnpm的run build如果构建失败会自动将package.json回滚到之前的版本并抛出错误避免留下版本号已改、代码没构建出来的半发布状态发布 npm执行packageManager publish --tag tag当使用 pnpm 时会自动追加--no-git-checks跳过 pnpm 对 git 状态的检查提交代码执行git add -A git commit -m release: 包名 v版本号若指定了--gitTag还会创建v版本号的 annotated tag推送远端将当前分支与可选的tags 推送到origin。包管理器的选择逻辑同样来自 manager.ts优先使用vant.config.mjs中build.packageManager的显式配置未配置时自动探测 yarn否则回退到 npm。对于 pnpm 工作区如 Vant 本仓库的 monorepo推荐在配置中显式指定packageManager以保证发布命令行为一致。commit-lint校验 commit messagevant-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包括类型说明fix修复缺陷feat新增功能docs文档变更perf性能优化test测试相关types类型定义变更style样式调整build构建流程相关chore杂项维护release发版提交refactor代码重构breaking change破坏性变更Merge branch foo into bar合并提交放行合法的提交格式为类型(可选作用域): 描述描述长度限制为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考