Vant CLI脚手架使用教程：快速搭建企业级UI组件库
项目地址: https://gitcode.com/gh_mirrors/va/vant 你是否还在为搭建UI组件库从零配置工程化工具链？是否在文档站点建设、组件打包优化上耗费大量精力？本文将带你通过Vant CLI（一个专为移动端UI组件库设计的工程化解决方案），仅需5步即可完成企业级组件库的初始化与部署，让你专注于组件开发而非构建流程。
读完本文你将掌握：
- 组件库项目的标准化目录设计
- 基于Vant CLI的全流程开发体验
- 组件文档与示例站点的自动化构建
- 企业级组件库的打包策略与版本管理
- 主题定制与按需引入的实现方案
1. 环境准备与脚手架安装
1.1 系统要求
确保开发环境满足以下条件：
- Node.js 14.0.0或更高版本（推荐使用Node.js 16+）
- npm、yarn或pnpm包管理器
- Git版本控制工具
1.2 安装Vant CLI
使用npm全局安装Vant CLI：
npm i @vant/cli -g
或通过pnpm安装（推荐）：
pnpm add @vant/cli -g
验证安装是否成功：
vant-cli --version
# 输出类似：vant-cli/7.0.0 darwin-x64 node-v16.14.2
2. 初始化组件库项目
2.1 使用create-vant-cli-app创建项目
Vant提供了项目生成器create-vant-cli-app，可快速创建标准化项目结构：
npx create-vant-cli-app@latest my-ui --template vue3
执行命令后会出现交互式配置选项：
? 请选择CSS预处理器 (Use arrow keys)
> Less
Sass
? 是否需要TypeScript支持? (Y/n) Y
2.2 项目结构解析
生成的项目采用业界最佳实践的目录结构，核心目录说明如下：
my-ui/
├── src/ # 组件源代码 (30%)
│ ├── button/ # 按钮组件
│ │ ├── demo/ # 组件示例
│ │ ├── index.ts # 组件入口
│ │ ├── index.less # 组件样式
│ │ └── README.md # 组件文档
├── docs/ # 静态文档 (25%)
│ ├── home.md # 文档首页
│ └── quickstart.md # 快速上手
├── vant.config.mjs # 项目配置文件 (20%)
├── package.json # 依赖管理 (15%)
└── tsconfig.json # TypeScript配置 (10%)
3. 核心配置详解
3.1 vant.config.mjs配置
该文件是Vant CLI的核心配置，控制组件库构建、文档站点等关键行为：
export default {
name: 'my-ui', // 组件库名称
build: {
css: {
preprocessor: 'less', // 样式预处理器
base: 'src/style/base.less' // 全局样式入口
},
site: {
publicPath: '/my-ui/' // 文档站点部署路径
},
bundleOptions: [ // 自定义打包格式
{ minify: true, formats: ['es', 'cjs'] },
{ minify: false, formats: ['umd'] }
]
},
site: {
title: 'My UI组件库',
logo: '/logo.png',
nav: [
{
title: '开发指南',
items: [
{ path: 'home', title: '介绍' },
{ path: 'quickstart', title: '快速上手' }
]
},
{
title: '基础组件',
items: [
{ path: 'button', title: 'Button 按钮' },
{ path: 'dialog', title: 'Dialog 对话框' }
]
}
]
}
};
关键配置项说明：
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| name | string | - | 组件库名称，用于生成package.json和UMD模块 |
| build.css.preprocessor | string | 'less' | 支持'less'或'sass'，决定样式文件的处理方式 |
| build.site.publicPath | string | '/' | 文档站点的基础路径，部署到子目录时需修改 |
| site.nav | Array | [] | 文档站点左侧导航结构，支持多级分组 |
| site.versions | Array | undefined | 多版本文档配置，用于版本切换功能 |
3.2 package.json配置
确保package.json中包含以下关键字段：
{
"main": "lib/index.js", // CommonJS入口
"module": "es/index.js", // ESModule入口
"typings": "lib/index.d.ts", // TypeScript类型声明
"files": ["es", "lib", "dist"], // 发布到npm的文件列表
"scripts": {
"dev": "vant-cli dev", // 开发环境
"build": "vant-cli build", // 构建组件库
"build:site": "vant-cli build-site", // 构建文档站点
"release": "vant-cli release" // 版本发布
}
}
4. 组件开发全流程
4.1 组件目录规范
单个组件的标准目录结构：
button/
├── demo/ # 示例代码
│ ├── basic.vue # 基础用法
│ ├── size.vue # 尺寸示例
│ └── index.vue # 示例入口
├── test/ # 单元测试
│ └── button.spec.ts
├── index.ts # 组件入口
├── index.less # 组件样式
├── README.md # 组件文档
└── types.ts # 类型定义
4.2 组件开发示例
以Button组件为例，创建src/button/index.ts：
import { defineComponent, PropType } from 'vue';
import './index.less';
export default defineComponent({
name: 'MyButton',
props: {
type: {
type: String as PropType<'primary' | 'success' | 'default'>,
default: 'default'
},
size: {
type: String as PropType<'large' | 'middle' | 'small'>,
default: 'middle'
},
disabled: {
type: Boolean,
default: false
}
},
setup(props, { slots }) {
return () => (
<button
class={`my-button my-button--${props.type} my-button--${props.size}`}
disabled={props.disabled}
>
{slots.default?.()}
</button>
);
}
});
对应的样式文件src/button/index.less：
@import '../style/mixins.less';
.my-button {
display: inline-block;
padding: @button-padding;
font-size: @button-font-size;
border-radius: @button-border-radius;
border: none;
cursor: pointer;
&--primary {
background-color: @primary-color;
color: #fff;
}
&--success {
background-color: @success-color;
color: #fff;
}
&:disabled {
opacity: 0.6;
cursor: not-allowed;
}
}
4.3 组件文档编写
在src/button/README.md中编写文档：
# Button 按钮
常用的操作按钮。
## 引入
```javascript
import { Button } from 'my-ui';
代码演示
基础用法
<Button type="primary">主要按钮</Button>
<Button type="success">成功按钮</Button>
尺寸大小
<Button size="large">大号按钮</Button>
<Button size="middle">中号按钮</Button>
<Button size="small">小号按钮</Button>
API
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 按钮类型 | 'primary' | 'success' | 'default' | 'default' |
| size | 按钮尺寸 | 'large' | 'middle' | 'small' | 'middle' |
| disabled | 是否禁用 | boolean | false |
## 5. 开发与构建流程
### 5.1 本地开发环境
启动开发服务器：
```bash
npm run dev
# 或使用npx直接运行
npx vant-cli dev
开发服务器特性：
- 组件代码热更新
- 文档自动生成与预览
- 手机模拟器实时预览
- ESLint代码校验
5.2 组件库构建
构建生产版本的组件代码：
npm run build
构建产物说明：
my-ui/
├── es/ # ESModule格式
│ ├── button/
│ ├── dialog/
│ └── index.js
├── lib/ # CommonJS格式
│ ├── button/
│ ├── dialog/
│ └── index.js
└── dist/ # UMD格式
├── my-ui.js
├── my-ui.min.js
└── my-ui.css
构建策略对比：
| 格式 | 用途 | 优势 | 适用场景 |
|---|---|---|---|
| ESModule | 现代构建工具 | 支持tree-shaking | Webpack/Rollup/Vite |
| CommonJS | Node环境 | 兼容性好 | 服务端渲染 |
| UMD | 浏览器直接引入 | 无需构建工具 | 快速演示/非模块化项目 |
5.3 文档站点构建
npm run build:site
构建后的文档站点位于site-dist目录，包含：
- 静态HTML/CSS/JS文件
- 响应式设计，支持PC/移动端
- 组件示例交互演示
- 全文搜索功能
部署选项：
- 静态托管服务（Netlify/Vercel/GitHub Pages）
- 企业内部服务器
- CDN加速分发
6. 高级特性与最佳实践
6.1 主题定制实现
通过样式变量覆盖实现主题定制：
- 创建自定义主题文件
theme.less：
// 覆盖默认变量
@primary-color: #1677ff;
@button-border-radius: 8px;
// 引入组件库样式
@import 'my-ui/es/style/index.less';
- 在vant.config.mjs中配置：
export default {
build: {
css: {
base: 'src/style/base.less'
}
}
};
- 提供主题定制文档，说明可修改的变量列表：
## 主题定制
通过修改LESS变量来自定义组件样式：
### 变量列表
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| @primary-color | #1989fa | 主要颜色 |
| @success-color | #07c160 | 成功颜色 |
| @warning-color | #ff976a | 警告颜色 |
| @danger-color | #f53f3f | 危险颜色 |
6.2 版本管理与发布
使用Vant CLI的release命令实现自动化版本管理：
npm run release
该命令会执行以下步骤：
- 运行lint和build检查
- 根据commit记录生成CHANGELOG
- 更新package.json版本号
- 创建Git标签
- 发布到npm仓库
版本号规则遵循SemVer规范：
- 主版本号(Major)：不兼容的API变更
- 次版本号(Minor)：向后兼容的功能新增
- 修订号(Patch)：向后兼容的问题修复
提交信息规范：
feat(button): add type 'info'
fix(dialog): correct position calculation
docs: update quickstart guide
6.3 测试策略
Vant CLI集成了Jest测试框架，创建src/button/test/button.spec.ts：
import { mount } from '@vue/test-utils';
import Button from '../index';
describe('Button', () => {
test('render type', () => {
const wrapper = mount(Button, {
props: { type: 'primary' }
});
expect(wrapper.classes()).toContain('my-button--primary');
});
test('disabled state', async () => {
const wrapper = mount(Button, {
props: { disabled: true }
});
expect(wrapper.attributes('disabled')).toBeDefined();
});
});
运行测试：
npm run test
7. 项目实战案例
7.1 组件库目录结构设计
企业级组件库推荐目录：
my-ui/
├── src/
│ ├── components/ # 基础组件
│ ├── business/ # 业务组件
│ ├── hooks/ # 组合式API
│ ├── utils/ # 工具函数
│ ├── style/ # 全局样式
│ └── index.ts # 入口文件
├── docs/
│ ├── guide/ # 开发指南
│ ├── api/ # API文档
│ └── changelog.md # 更新日志
├── test/ # 单元测试
└── scripts/ # 自定义脚本
7.2 按需引入实现
通过babel-plugin-import实现组件按需引入：
// babel.config.js
module.exports = {
plugins: [
[
'import',
{
libraryName: 'my-ui',
libraryDirectory: 'es',
style: true
},
'my-ui'
]
]
};
使用方式：
import { Button, Dialog } from 'my-ui';
编译后自动转换为：
import Button from 'my-ui/es/button';
import 'my-ui/es/button/style';
import Dialog from 'my-ui/es/dialog';
import 'my-ui/es/dialog/style';
8. 部署与维护
8.1 GitHub Pages部署流程
- 在package.json中添加部署脚本：
{
"scripts": {
"release:site": "npm run build:site && gh-pages -d site-dist"
}
}
- 安装部署工具：
npm i gh-pages -D
- 执行部署：
npm run release:site
8.2 长期维护策略
维护建议：
- 定期更新依赖，修复安全漏洞
- 建立Issue模板，规范bug报告
- 维护详细的CHANGELOG
- 提供迁移指南，减少升级成本
- 活跃响应社区反馈
总结与展望
通过Vant CLI，我们实现了从组件开发到文档部署的全流程工程化解决方案。其核心价值在于：
- 标准化：提供业界最佳实践的项目结构与配置
- 自动化：文档生成、代码构建、版本发布的自动化流程
- 专业化：针对UI组件库场景的深度优化
- 可扩展性：灵活的配置系统支持定制化需求
随着Web技术的发展，组件库开发将面临更多挑战：
- Web Components跨框架兼容
- 设计系统与组件库的深度融合
- AI辅助的组件开发与文档生成
掌握Vant CLI不仅能解决当前的组件库工程化问题，更能帮助开发者理解现代前端工程化的核心思想，为未来技术变革做好准备。
立即开始使用Vant CLI构建你的第一个企业级UI组件库：
npx create-vant-cli-app@latest my-ui --template vue3
cd my-ui
npm run dev
让工程化工具为你赋能，专注创造真正有价值的组件！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
