在移动互联网时代，移动端H5应用的开发效率和用户体验至关重要。Vant是由有赞前端团队于2017年开源的移动端Vue组件库，历经多个版本的迭代，已经成为国内移动端H5开发的事实标准之一。Vant 4作为Vue 3时代的主力版本，于2022年12月正式发布，带来了深色模式、5个新组件、更轻量的体积和更现代化的开发体验。
截至2026年初，Vant在GitHub上已获得超过2.2万Star，每周下载量超过30万次。它以其极致的轻量化（组件平均体积小于1KB）、零外部依赖、完善的TypeScript支持和丰富的组件生态，赢得了广大开发者的青睐。
本文将系统全面地梳理Vant 4的核心知识点，从设计理念到安装配置，从核心组件到进阶用法，从主题定制到性能优化，帮助读者建立完整的知识体系，能够熟练运用Vant 4构建高质量的移动端H5应用。
一、Vant 4概述
1.1 什么是Vant
Vant是一个轻量、可定制的移动端Vue组件库，由有赞前端团队开发和维护。它提供了一套高质量的移动端UI组件，帮助开发者快速构建移动端H5应用。Vant官方提供了Vue 2版本（Vant 2）、Vue 3版本（Vant 4）和微信小程序版本（Vant Weapp），并由社区团队维护React版本和支付宝小程序版本。
Vant的核心设计理念可以概括为三个关键词：
1.2 Vant 4的核心特性
Vant 4相较于Vant 3带来了多项重要更新：
1.3 Vant 4 vs 其他移动端组件库
1.4 Vant版本状态
目前Vant各个版本的维护状态如下：
选择建议：新项目请使用Vant 4（Vue 3），Vant 3已不再维护，不建议用于新项目。如果你仍在使用Vue 2，可以考虑Vant 2或升级到Vue 3。
二、安装与配置
2.1 安装Vant
# 使用npm安装
npm install vant@4 --save
# 使用yarn安装
yarn add vant@4
# 使用pnpm安装（推荐）
pnpm add vant@4
2.2 按需引入（自动按需加载）
Vant 4推荐使用按需加载方案，可以显著减小打包体积。根据实测数据，全量引入Vant会使打包体积增加约200KB，而按需引入后仅增加使用到的组件体积。
Vant 4不再支持babel-plugin-import，官方推荐使用unplugin-vue-components和unplugin-auto-import插件实现自动按需加载。
步骤1：安装依赖
pnpm add @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D
步骤2：配置Vite
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from '@vant/auto-import-resolver';
export default defineConfig({
plugins: [
vue(),
AutoImport({
resolvers: [VantResolver()],
imports: ['vue'], // 自动导入Vue内置API
}),
Components({
resolvers: [VantResolver()],
}),
],
});
步骤3：使用组件
配置完成后，在模板中可以直接使用Vant组件，无需手动导入：
<template>
<van-button type="primary">按钮</van-button>
<van-cell title="单元格" value="内容" />
</template>
<script setup>
// 无需手动引入组件
// 无需手动引入样式
</script>
2.3 全量引入（快速上手）
对于小型项目或原型开发，也可以选择全量引入：
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import Vant from 'vant';
import 'vant/lib/index.css';
const app = createApp(App);
app.use(Vant);
app.mount('#app');
2.4 手动按需引入
如果无法使用自动按需加载插件，也可以手动引入组件和样式：
import Button from 'vant/es/button';
import 'vant/es/button/style';
app.use(Button);
2.5 函数式API的自动引入
对于showToast、showDialog等函数式API，需要额外配置自动引入：
// vite.config.ts
AutoImport({
imports: ['vue'],
resolvers: [
VantResolver(),
// 自定义resolver处理函数式API
(name) => {
if (name.startsWith('show') || name.startsWith('close')) {
return { from: 'vant' };
}
},
],
}),
配置完成后，可以直接在代码中使用函数式API：
<script setup>
// 直接使用，无需导入
showToast({ message: '操作成功', type: 'success' });
</script>
