vant-weapp：有赞轻量可靠的微信小程序 UI 组件库安装与使用指南

Vant Weapp 是有赞（Youzan）开源的微信小程序 UI 组件库，2017 年开源，主打「轻量、可靠」。它提供按钮、单元格、弹窗、表单、导航、宫格、TAB 等数十个高质量小程序自定义组件，样式贴近移动端电商场景，是目前小程序里最流行的第三方组件库之一。Vant 官方同时维护 Vue 2 / Vue 3 版本，本文聚焦微信小程序版本 @vant/weapp。

一、项目官方信息

二、官方图片

Vant 官方 Logo：

扫码可在微信里体验组件库示例小程序（官方提示：因审核机制，线上示例未必是最新版，建议 clone 代码到开发者工具预览）：

三、环境要求

• 已安装微信开发者工具，并注册/拥有一个小程序 AppID；
• 本地具备 Node.js / npm 环境（用于 npm 安装依赖）；
• 阅读过微信官方的小程序简易教程与自定义组件介绍；
• 小程序基础库版本不低于 2.6.5。

四、部署/接入步骤

方式一：通过 npm 安装（官方推荐）

小程序自基础库起已支持 npm 安装第三方包，在你的小程序工程根目录执行：

# 通过 npm 安装
npm i @vant/weapp -S --production

# 或通过 yarn 安装
yarn add @vant/weapp --production

如果要安装 0.x 老版本，包名是 vant-weapp：npm i vant-weapp -S --production。

安装后，必须在微信开发者工具里执行「构建 npm」：菜单栏「工具 → 构建 npm」。工具会把 node_modules/@vant/weapp 处理成小程序可识别的 miniprogram_npm 目录，之后才能在 usingComponents 里引用。

方式二：下载源码拷贝 dist

不使用 npm 时，可直接 clone 源码，把 dist 目录拷进自己项目：

git clone https://github.com/youzan/vant-weapp.git

本地预览官方示例

# 进入克隆下来的工程，安装依赖
npm install

# 执行组件编译（监听改动）
npm run dev

然后打开微信开发者工具，把 vant-weapp/example 目录添加进去即可预览全部组件示例。

省市区选择组件 van-area 的地区数据，官方建议直接在云开发环境导入 vant-weapp/example/database_area.JSON 文件使用。

五、使用方法

1. 注册组件（json）

以按钮组件为例，在需要使用页面的 .json 中，通过 usingComponents 引入对应自定义组件：

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

如果走 npm + 构建 npm 的方式，路径一般写成 /miniprogram_npm/@vant/weapp/button/index。

2. 在 wxml 中使用组件

注册后，直接在页面 WXML 里以标签形式使用：

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

3. 常用组件接入示例

• 单元格列表：

<van-cell-group>
  <van-cell title="单元格一" value="内容" />
  <van-cell title="单元格二" value="内容" is-link />
</van-cell-group>

• 弹窗：

<van-dialog use-title title="标题" show-cancel-button>{{ content }}</van-dialog>

• 表单输入：

<van-field model:value="{{ value }}" label="用户名" placeholder="请输入用户名" />

每个组件的完整属性、事件、示例都可在官方文档（https://vant.pro/vant-weapp/）按组件名查阅。

六、常见问题 FAQ

Q1：npm 装完了，在 json 里引用组件却报「组件未找到」？ 小程序不能直接读 node_modules，必须在微信开发者工具执行「工具 → 构建 npm」，生成 miniprogram_npm 目录后再引用。

Q2：van-area 省市区数据怎么初始化？ 官方建议在云开发环境直接导入 vant-weapp/example/database_area.JSON 作为地区数据源。

Q3：线上扫码的示例小程序组件不是最新版？ 官方说明因微信审核机制，示例小程序有滞后；想看最新组件效果，请 clone 仓库后 npm install && npm run dev，用开发者工具打开 example 目录预览。

Q4：基础库有什么要求？ Vant Weapp 最低支持小程序基础库 2.6.5，过低需在开发者工具「详情 → 本地设置」或管理后台调高基础库版本。

Q5：组件样式和设计稿对不上？ Vant 提供设计资源（见文档站「设计」章节），并支持通过 CSS 变量/主题定制调整主色等；具体变量名以官方文档各组件的「主题定制」小节为准。

Q6：npm 包名为什么有两个？ 新版统一为 @vant/weapp（带作用域）；0.x 老版本包名是 vant-weapp，新项目请一律用 @vant/weapp。

七、跳转链接

• GitHub 仓库：https://github.com/youzan/vant-weapp
• 官方文档（国内）：https://vant.pro/vant-weapp/
• 官方文档（GitHub）：https://vant-ui.github.io/vant-weapp/
• npm 包：https://www.npmjs.com/package/@vant/weapp
• 官方示例：https://github.com/vant-ui/vant-demo