Vant Weapp · 有赞开源的轻量可靠微信小程序 UI 组件库｜安装与使用全指南

项目仓库： https://github.com/youzan/vant-weapp

开源协议：MIT · 出品：有赞（Vant，2017 年开源） · npm 包：@vant/weapp · 最低基础库：2.6.5 · 文档：vant-ui.github.io/vant-weapp

1 项目简介

Vant 是一个轻量、可靠的移动端组件库，2017 年开源。Vant 官方提供 Vue 2 版、Vue 3 版与微信小程序版本（即 Vant Weapp），社区团队维护 React 版与支付宝小程序版。Vant Weapp 是面向微信小程序的原生 UI 组件库。

1.1 核心信息一览

1.2 适用场景

• 微信小程序项目快速搭建常用 UI（按钮、表单、弹窗、列表、省市区等）。
• 团队不想从零写小程序组件，直接用成熟组件库。

1.3 能力边界（官方口径）

• 使用前请先学微信官方小程序简易教程与自定义组件介绍。
• 最低支持小程序基础库 2.6.5。
• 示例小程序因微信审核机制可能不是最新版，建议 clone 代码到本地开发者工具预览。

2 功能特性

• 轻量可靠：有赞出品，生产验证。
• 丰富组件：按钮、表单、弹窗、列表、省市区选择（Area）等。
• 多端版本：Vue 2/3、React、支付宝小程序版本。
• npm 安装：小程序已支持 npm 安装第三方包。

3 官方界面预览

开头封面为 Vant 官方 Logo。组件库示例可扫官方二维码体验，或 clone 后用微信开发者工具打开 example 目录预览。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• 微信开发者工具；Node.js / npm。
• 已学微信小程序自定义组件机制。

5.2 硬件建议

• 普通开发机；组件库无服务器运行时。

5.3 端口与资源

• 无；纯前端组件库。

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

npm i @vant/weapp -S --production
# 或 yarn
yarn add @vant/weapp --production

在页面 json 中引入组件：

{
  "usingComponents": {
    "van-button": "/path/to/vant-weapp/dist/button/index"
  }
}

在 wxml 中使用：

<van-button type="primary">按钮</van-button>

7 方式二：下载源码

git clone https://github.com/youzan/vant-weapp.git
# 将 dist 目录拷贝到自己的项目中

8 配置项说明

• 通过 usingComponents 按需引入组件路径。
• Area 省市区组件的地区数据可在云开发环境导入 vant-weapp/example/database_area.JSON。

9 常用运维命令

• 预览示例：npm install && npm run dev，微信开发者工具打开 example 目录。
• 升级：npm i @vant/weapp@latest。

10 常见故障排查

• 组件不显示：检查 usingComponents 路径与 npm 构建是否在开发者工具中执行。
• 基础库过低：升级到 2.6.5 以上。

11 风险与合规说明

• 许可证：MIT。
• 本文整理自官方 README，命令以官方文档最新说明为准；不包含 star 数等动态数据。