🚀 快速上手 - 5 分钟让你爱上 Vant！

🎯 开始你的 Vant 之旅

欢迎来到 Vant 的世界！这里将带你快速掌握 Vant 的安装方法和基本使用技巧。无论你是前端新手还是资深开发者，都能在这里找到最适合的上手方式。

💡 小贴士：建议先花 2 分钟浏览一下整个文档，然后选择最适合你的安装方式开始实践！

📦 安装 Vant

🔧 方式一：npm 安装（推荐）

这是最常用也是最推荐的安装方式，适合大部分项目场景：

bash

# 🎉 Vue 3 项目，安装最新版 Vant（推荐）
npm i vant

# 🔄 Vue 2 项目，安装 Vant 2（维护版本）
npm i vant@latest-v2

其他包管理器：

bash

# 🧶 通过 yarn 安装（速度快）
yarn add vant

# 📦 通过 pnpm 安装（节省空间）
pnpm add vant

# ⚡ 通过 Bun 安装（超快速度）
bun add vant

🌟 为什么选择 npm 安装？
✅ 支持 Tree Shaking，自动优化包体积
✅ 完整的 TypeScript 支持
✅ 可以使用所有高级功能
✅ 便于版本管理和更新

🆕 创建新项目

准备开始一个全新的项目？我们为你精心挑选了几个最佳的构建工具：

🏆 Rsbuild（强烈推荐）

为什么选择 Rsbuild？

⚡ 超快构建：基于 Rspack，构建速度比 Webpack 快 5-10 倍
🎯 官方支持：由 Vant 作者亲自开发，对 Vant 提供第一优先级支持
🛠️ 开箱即用：零配置即可开始开发
🔧 现代化：支持最新的前端技术栈

bash

# 🚀 一键创建 Rsbuild 项目
npm create rsbuild@latest

💡 小贴士：选择 Vue 模板，然后安装 Vant，就能立即开始开发了！

🌟 其他优秀选择

Vite：轻量快速，开发体验极佳
Nuxt：全栈框架，支持 SSR/SSG

📚 官方示例项目

不想从零开始？直接使用我们的示例项目，拿来即用：

项目	技术栈	特色
🏗️ Rsbuild 示例	Vue 3 + Vant 4 + Rsbuild	🚀 极速构建，官方推荐
⚡ Vite 示例	Vue 3 + Vant 4 + Vite	🔥 热更新，开发体验佳
🌐 Nuxt3 示例	Vue 3 + Nuxt 3 + Vant 4	📱 SSR 支持，SEO 友好

🎯 快速开始：git clone 任意一个示例项目，然后 npm install && npm run dev 即可！

🌐 方式二：CDN 引入（适合快速原型）

想要快速验证想法或制作简单页面？CDN 引入是你的最佳选择！

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>🎉 我的第一个 Vant 页面</title>
  
  <!-- 🎨 引入 Vant 样式文件 -->
  <link
    rel="stylesheet"
    href="https://fastly.jsdelivr.net/npm/vant@4/lib/index.css"
  />
</head>
<body>
  <div id="app">
    <!-- 📱 这里将渲染我们的移动端应用 -->
  </div>

  <!-- 🔧 引入 Vue 和 Vant 的 JS 文件 -->
  <script src="https://fastly.jsdelivr.net/npm/vue@3"></script>
  <script src="https://fastly.jsdelivr.net/npm/vant@4/lib/vant.min.js"></script>

  <script>
    // 🚀 创建 Vue 应用
    const app = Vue.createApp({
      template: `
        <div style="padding: 20px;">
          <h2>🎉 欢迎使用 Vant！</h2>
          <van-button type="primary" @click="handleClick">
            点击我试试
          </van-button>
        </div>
      `,
      methods: {
        handleClick() {
          // 📢 调用 Vant 的 Toast 组件
          vant.showToast('🎊 恭喜你，成功使用 Vant！');
        }
      }
    });
    
    // 🔌 注册 Vant 组件
    app.use(vant);
    
    // 🖼️ 如果需要使用图片懒加载，手动注册 Lazyload
    app.use(vant.Lazyload);
    
    // 🎯 挂载应用
    app.mount('#app');
  </script>
</body>
</html>

💡 试试看：复制上面的代码到一个 HTML 文件中，用浏览器打开，你就能看到一个可以工作的 Vant 应用了！

🌐 免费 CDN 服务

以下是一些优质的免费 CDN 服务，任选其一即可：

CDN 服务	特点	链接
🚀 jsDelivr	全球 CDN，速度快，稳定性好	查看详情
📦 cdnjs	Cloudflare 提供，覆盖全球	查看详情
🔗 unpkg	npm 官方 CDN，实时同步	查看详情

⚠️ 使用建议

适用场景：

✅ 快速原型开发
✅ 学习和实验
✅ 个人小项目
✅ 技术演示

企业级项目建议：

🏢 npm 安装 + 构建工具打包（推荐）
🏢 下载文件并托管在自己的 CDN 上
🏢 使用私有 npm 仓库

🔒 安全提示：生产环境建议使用自托管方式，避免第三方 CDN 的潜在风险。

🎯 学习示例

📚 官方示例工程

想要深入学习 Vant？我们为你准备了丰富的示例工程！

🎓 你将学到什么？

学习内容	难度	收获
🏗️ 基于 Rsbuild 搭建应用	⭐⭐	掌握最新构建工具
⚡ 基于 Vite 搭建应用	⭐⭐	体验极速开发
🌐 基于 Nuxt 搭建应用	⭐⭐⭐	学会 SSR 开发
🔧 基于 Vue CLI 搭建应用	⭐⭐	传统构建方式
📦 配置按需引入组件	⭐⭐⭐	优化包体积
📱 配置 Rem 适配方案	⭐⭐⭐	移动端适配
🖥️ 配置 Viewport 适配方案	⭐⭐⭐	响应式设计
🔷 配置 TypeScript 工程	⭐⭐⭐⭐	类型安全开发

🎯 学习建议：建议从 Rsbuild 示例开始，它是最现代化的方案！

🔧 引入组件

🌟 方法一：常规用法（推荐新手）

这是最简单直接的使用方式，适合快速上手：

import { createApp } from 'vue';
// 🎯 1. 引入你需要的组件
import { Button } from 'vant';
// 🎨 2. 引入组件样式
import 'vant/lib/index.css';

const app = createApp();

// 🔌 3. 注册你需要的组件
app.use(Button);

🎉 优势：

✅ 简单易懂：三步即可完成配置
✅ 自动优化：支持 Tree Shaking，自动移除未使用的 JS 代码
✅ 零配置：无需额外插件配置
✅ 稳定可靠：不依赖第三方插件

📖 更多注册方式： Vant 支持多种组件注册方式：

🌍 全局注册
📍 局部注册
🔄 动态注册

💡 小贴士：虽然 JS 代码会自动优化，但 CSS 样式会全量引入。如果你的项目对 CSS 体积要求极致，可以考虑下面的方法二。

⚡ 方法二：按需引入样式（进阶优化）

想要极致的包体积优化？这个方法适合你！

🎯 适用场景：

📱 对包体积要求极致的移动端应用
🚀 需要极快加载速度的项目
💰 流量敏感的应用

🔧 技术原理：使用 unplugin-vue-components 插件自动引入组件，配合 Vant 官方的 @vant/auto-import-resolver 解析器，实现 CSS 样式的按需引入。

⚖️ 权衡考虑：

✅ 优势：CSS 体积更小，加载更快
❌ 劣势：配置稍微复杂，依赖第三方插件

💡 建议：如果你的项目对 CSS 体积要求不是特别极致，推荐使用更简便的方法一。

🔧 步骤一：安装插件

bash

# 📦 npm 安装
npm i @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

# 🧶 yarn 安装
yarn add @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

# 📦 pnpm 安装
pnpm add @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

# ⚡ bun 安装
bun add @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

⚙️ 步骤二：配置插件

根据你的构建工具选择对应的配置方式：

🏗️ Rsbuild 项目配置

在 rsbuild.config.js 文件中配置：

import { defineConfig } from '@rsbuild/core';
import { pluginVue } from '@rsbuild/plugin-vue';
import AutoImport from 'unplugin-auto-import/rspack';
import Components from 'unplugin-vue-components/rspack';
import { VantResolver } from '@vant/auto-import-resolver';

export default defineConfig({
  plugins: [pluginVue()],
  tools: {
    rspack: {
      plugins: [
        // 🔄 自动导入 Vant 组件的 API
        AutoImport({
          resolvers: [VantResolver()],
        }),
        // 🎨 自动导入 Vant 组件和样式
        Components({
          resolvers: [VantResolver()],
        }),
      ],
    },
  },
});

⚡ Vite 项目配置

在 vite.config.js 文件中配置：

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(),
    // 🔄 自动导入 Vant 组件的 API
    AutoImport({
      resolvers: [VantResolver()],
    }),
    // 🎨 自动导入 Vant 组件和样式
    Components({
      resolvers: [VantResolver()],
    }),
  ],
});

🔧 Webpack / Vue CLI 项目配置

在 webpack.config.js 或 vue.config.js 文件中配置：

const AutoImport = require('unplugin-auto-import/webpack');
const Components = require('unplugin-vue-components/webpack');
const { VantResolver } = require('@vant/auto-import-resolver');

module.exports = {
  // ...其他配置
  plugins: [
    // 🔄 自动导入 Vant 组件的 API
    AutoImport({
      resolvers: [VantResolver()],
    }),
    // 🎨 自动导入 Vant 组件和样式
    Components({
      resolvers: [VantResolver()],
    }),
  ],
};

🎯 配置说明：
AutoImport：自动导入组件的 API（如 showToast、showDialog 等）
Components：自动导入组件本身和对应的 CSS 样式

🎉 步骤三：开始使用

配置完成后，你就可以享受自动导入的便利了！

vue

<template>
  <!-- ✨ 无需手动导入，直接使用 Vant 组件 -->
  <van-button type="primary" @click="showToast('success')">
    点击我试试
  </van-button>
  <van-cell title="自动导入真香！" />
</template>

<script setup>
// 🎯 无需手动导入，直接使用 Vant 的 API
showToast('Hello Vant!');

// 🔥 也可以使用其他 API
const showSuccess = () => {
  showToast({
    type: 'success',
    message: '操作成功！'
  });
};
</script>

🎊 享受的便利：

✅ 零导入：无需手动 import 组件和样式
✅ 智能提示：IDE 自动提示可用组件
✅ 按需加载：只打包使用到的组件和样式
✅ 类型安全：完整的 TypeScript 支持

⚠️ 使用提示

🚨 重要注意事项：

❌ 避免混用：不要同时使用「全量引入」和「按需引入」，会导致代码重复
🐛 问题反馈：组件导入问题请到 unplugin-vue-components 反馈
🎨 样式问题：样式相关问题请到 Vant 仓库反馈

🔧 版本兼容性：

当 unplugin-vue-components >= 0.26.0 时，webpack/vue-cli/rspack 需要使用 ComponentsPlugin.default
更多配置选项请查看 @vant/auto-import-resolver 文档

🌐 在框架中使用

🌟 在 Nuxt 3 中使用

🎯 推荐方案：使用官方的 vant-nuxt 模块，享受开箱即用的体验！

✨ 特色功能：

🔄 自动引入组件
🎨 按需引入样式
📱 支持函数组件
🚀 零配置使用

📦 步骤一：安装模块

bash

# 📦 npm 安装
npm i @vant/nuxt -D

# 🧶 yarn 安装
yarn add @vant/nuxt -D

# 📦 pnpm 安装
pnpm add @vant/nuxt -D

# ⚡ bun 安装
bun add @vant/nuxt -D

⚙️ 步骤二：配置模块

在 nuxt.config.js 文件中添加模块：

export default defineNuxtConfig({
  // 🔌 添加 Vant Nuxt 模块
  modules: ['@vant/nuxt'],
  
  // 🎨 可选：自定义配置
  vant: {
    /** Vant 配置选项 */
  }
});

🎉 步骤三：开始使用

配置完成后，就可以直接使用 Vant 组件了！

vue

<template>
  <div>
    <!-- 🎯 标准写法 -->
    <van-button type="primary" @click="showToast('toast')">
      显示提示
    </van-button>
    
    <!-- 🔤 PascalCase 写法 -->
    <VanButton type="success" @click="showNotify('notify')">
      显示通知
    </VanButton>
    
    <!-- ⚡ 懒加载写法 -->
    <LazyVanButton type="default">
      懒加载按钮
    </LazyVanButton>
  </div>
</template>

<script setup>
// 🎯 直接使用 API，无需导入
const handleClick = () => {
  showToast({
    type: 'success',
    message: 'Nuxt + Vant 真香！'
  });
};
</script>

📚 了解更多：查看 Nuxt 组件文档了解组件的更多用法。

🔄 迁移指南

告别 babel-plugin-import

🎉 好消息：Vant 4.0+ 不再需要 babel-plugin-import！

如果你的项目还在使用，请立即移除：

diff

// babel.config.js
module.exports = {
  plugins: [
-    ['import', {
-      libraryName: 'vant',
-      libraryDirectory: 'es',
-      style: true
-    }, 'vant']
  ]
};

🚀 移除后的收益

收益	说明
⚡ 编译更快	可以使用 esbuild、swc 等现代编译工具
🔓 导入更灵活	可以导入工具函数、类型定义等
🛠️ 配置更简单	减少 babel 配置复杂度
🔧 兼容性更好	支持更多构建工具和框架

💡 现在你可以这样导入：

// 🎯 导入组件
import { Button, Cell } from 'vant';

// 🔧 导入 API 函数
import { showToast, showDialog } from 'vant';

// 📝 导入类型定义（TypeScript）
import type { ButtonType, CellProps } from 'vant';

🎯 迁移提示：

✅ 移除插件后，现有代码无需修改
✅ 建议使用方法一（常规用法）或方法二（按需引入）
✅ 享受更快的编译速度和更灵活的导入方式

📚 相关内容

🚀 快速开始

🏠 项目介绍 - 了解 Vant 的特色和优势
🎨 设计理念 - 深入理解 Vant 的设计思想
❓ 常见问题 - 解决开发中的常见疑问

🔧 开发指南

📱 组件总览 - 浏览所有可用组件
🌈 定制主题 - 打造专属的视觉风格
🌍 国际化 - 支持多语言应用

🛠️ 开发工具

📦 官方示例 - 完整的项目示例
🎮 在线体验 - 在线预览所有组件
🔍 组件搜索 - 快速找到需要的组件
📖 API 文档 - 详细的组件 API

🌐 多端支持

📱 Vant Weapp - 微信小程序版本
🚀 Vant React - React 版本
💻 Vant CLI - 组件库构建工具

🎯 构建工具集成

🏗️ Rsbuild 集成 - 现代化构建工具
⚡ Vite 集成 - 极速开发体验
🌐 Nuxt 集成 - 全栈 Vue 框架
🔧 Webpack 集成 - 传统构建方案

💡 最佳实践

🎨 样式定制 - 个性化主题定制

🤝 社区与支持

💬 讨论区 - 技术交流和问题讨论
🐛 问题反馈 - 报告 Bug 和功能建议
📝 更新日志 - 了解最新变化
🎯 贡献指南 - 参与开源贡献

📖 学习资源

🎓 Vue 3 官方文档 - Vue 3 基础知识
📚 组合式 API - 现代 Vue 开发方式
🔷 TypeScript 指南 - 类型安全开发
📱 移动端开发指南 - PWA 开发实践

🚀 快速上手 - 5 分钟让你爱上 Vant！ ​

🎯 开始你的 Vant 之旅 ​

📦 安装 Vant ​

🔧 方式一：npm 安装（推荐） ​

🆕 创建新项目 ​

🏆 Rsbuild（强烈推荐） ​

🌟 其他优秀选择 ​

📚 官方示例项目 ​

🌐 方式二：CDN 引入（适合快速原型） ​

🌐 免费 CDN 服务 ​

⚠️ 使用建议 ​

🎯 学习示例 ​

📚 官方示例工程 ​

🔧 引入组件 ​

🌟 方法一：常规用法（推荐新手） ​

⚡ 方法二：按需引入样式（进阶优化） ​

🔧 步骤一：安装插件 ​

⚙️ 步骤二：配置插件 ​

🏗️ Rsbuild 项目配置 ​

⚡ Vite 项目配置 ​

🔧 Webpack / Vue CLI 项目配置 ​

🎉 步骤三：开始使用 ​

⚠️ 使用提示 ​

🌐 在框架中使用 ​

🌟 在 Nuxt 3 中使用 ​

📦 步骤一：安装模块 ​

⚙️ 步骤二：配置模块 ​

🎉 步骤三：开始使用 ​

🔄 迁移指南 ​

告别 babel-plugin-import ​

🚀 移除后的收益 ​

📚 相关内容 ​

🚀 快速开始 ​

🔧 开发指南 ​

🛠️ 开发工具 ​

🌐 多端支持 ​

🎯 构建工具集成 ​

💡 最佳实践 ​

🤝 社区与支持 ​

📖 学习资源 ​

🚀 快速上手 - 5 分钟让你爱上 Vant！

🎯 开始你的 Vant 之旅

📦 安装 Vant

🔧 方式一：npm 安装（推荐）

🆕 创建新项目

🏆 Rsbuild（强烈推荐）

🌟 其他优秀选择

📚 官方示例项目

🌐 方式二：CDN 引入（适合快速原型）

🌐 免费 CDN 服务

⚠️ 使用建议

🎯 学习示例

📚 官方示例工程

🔧 引入组件

🌟 方法一：常规用法（推荐新手）

⚡ 方法二：按需引入样式（进阶优化）

🔧 步骤一：安装插件

⚙️ 步骤二：配置插件

🏗️ Rsbuild 项目配置

⚡ Vite 项目配置

🔧 Webpack / Vue CLI 项目配置

🎉 步骤三：开始使用

⚠️ 使用提示

🌐 在框架中使用

🌟 在 Nuxt 3 中使用

📦 步骤一：安装模块

⚙️ 步骤二：配置模块

🎉 步骤三：开始使用

🔄 迁移指南

告别 babel-plugin-import

🚀 移除后的收益

📚 相关内容

🚀 快速开始

🔧 开发指南

🛠️ 开发工具

🌐 多端支持

🎯 构建工具集成

💡 最佳实践

🤝 社区与支持

📖 学习资源