🚀 快速上手 - 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 的設計思想
❓ 常見問題 - 解決開發中的常見疑問

🛠️ 開發工具

📦 官方範例 - 完整的專案範例
🎮 線上體驗 - 線上預覽所有元件
🔍 元件搜尋 - 快速找到需要的元件
📖 API 文件 - 詳細的元件 API

🌐 多端支援

📱 Vant Weapp - 微信小程式版本
🚀 Vant React - React 版本
💻 Vant CLI - 元件庫建置工具

🎯 建置工具整合

🏗️ Rsbuild 整合 - 現代化建置工具
⚡ Vite 整合 - 極速開發體驗
🌐 Nuxt 整合 - 全端 Vue 框架
🔧 Webpack 整合 - 傳統建置方案

💡 最佳實踐

🎨 設計理念 - 深入理解 Vant 的設計思想

🤝 社群與支援

💬 討論區 - 技術交流和問題討論
🐛 問題回饋 - 回報 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

🚀 移除後的收益

📚 相關內容

🚀 快速開始

🛠️ 開發工具

🌐 多端支援

🎯 建置工具整合

💡 最佳實踐

🤝 社群與支援

📖 學習資源