2025最新vant-weapp入门指南：从npm安装到组件渲染全流程

你是否还在为小程序开发中的UI组件美观度不足而烦恼？是否在寻找一套既轻便又强大的组件库来提升开发效率？本文将带你从零开始，掌握vant-weapp组件库的安装、配置、使用及样式定制全流程，让你的小程序界面瞬间提升一个档次。读完本文，你将能够：成功安装vant-weapp组件库、正确配置小程序项目、熟练使用各类基础组件、根据需求定制组件样式。

一、vant-weapp简介

vant-weapp是有赞前端团队开发的一套基于微信小程序的UI组件库，它提供了丰富的组件，如按钮、表单、导航等，能够帮助开发者快速构建美观、高效的小程序界面。该组件库具有轻量、易用、美观等特点，深受广大小程序开发者的喜爱。

官方文档：docs/markdown/quickstart.md

二、安装与配置

2.1 安装vant-weapp

使用npm安装vant-weapp是最常用的方式，在项目根目录下执行以下命令：

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

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

2.2 修改app.json

将app.json中的"style": "v2"去除，小程序的新版基础组件强行加上了许多样式，难以覆盖，不关闭将造成部分组件样式混乱。

2.3 修改project.config.json

开发者工具创建的项目，miniprogramRoot默认为miniprogram，package.json在其外部，npm构建无法正常工作。需要手动在project.config.json内添加如下配置，使开发者工具可以正确索引到npm依赖的位置。

{
  ...
  "setting": {
    ...
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "packageJsonPath": "./package.json",
        "miniprogramNpmDistDir": "./miniprogram/"
      }
    ]
  }
}

注意：由于目前新版开发者工具创建的小程序目录文件结构问题，npm构建的文件目录为miniprogram_npm，并且开发工具会默认在当前目录下创建miniprogram_npm的文件名，所以新版本的miniprogramNpmDistDir配置为'./'即可。

2.4 构建npm包

打开微信开发者工具，点击工具 -> 构建 npm，并勾选使用 npm 模块选项，构建完成后，即可引入组件。

三、基础组件使用

3.1 引入组件

以Button组件为例，只需要在app.json或index.json中配置Button对应的路径即可。

// 通过 npm 安装
// app.json
"usingComponents": {
  "van-button": "@vant/weapp/button/index"
}

Button组件源码路径：lib/button/

3.2 使用组件

引入组件后，可以在wxml中直接使用组件

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

四、样式定制

4.1 解除样式隔离

Vant Weapp的所有组件都开启了addGlobalClass: true以接受外部样式的影响，可以在页面的样式文件中直接覆盖样式。

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

/* page.wxss */
.van-button--primary {
  font-size: 20px;
  background-color: pink;
}

在自定义组件中使用Vant Weapp组件时，需开启styleIsolation: 'shared'选项。

样式覆盖详细说明：docs/markdown/custom-style.md

4.2 使用CSS变量定制主题

Vant Weapp使用CSS变量来实现定制主题，你可以在wxss中为组件设置CSS变量，也可以通过style属性来设置，实现主题的动态切换。

<van-button class="my-button">
  默认按钮
</van-button>

.my-button {
  --button-border-radius: 10px;
  --button-default-color: #f2f3f5;
}

定制主题详细教程：docs/markdown/theme.md

五、示例工程运行

5.1 克隆项目并安装依赖

# 将项目克隆到本地
git clone https://gitcode.com/gh_mirrors/van/vant-weapp.git

# 安装项目依赖
cd vant-weapp && npm install

# 执行组件编译
npm run dev

5.2 在开发者工具中预览

打开微信开发者工具，导入example目录的项目就可以预览示例了。示例项目路径：example/

六、总结与展望

通过本文的介绍，相信你已经掌握了vant-weapp的基本使用方法。从安装配置到组件使用，再到样式定制，每一个环节都至关重要。在实际开发中，你可以根据项目需求，灵活运用vant-weapp提供的各类组件和样式定制功能，打造出更加优秀的小程序界面。

未来，vant-weapp团队还会不断优化组件性能，增加更多实用组件，为小程序开发提供更好的支持。如果你在使用过程中遇到任何问题，可以查阅官方文档或在社区中寻求帮助。

希望本文对你有所帮助，如果你觉得不错，欢迎点赞、收藏、关注，后续我们还会推出更多关于vant-weapp的进阶教程。