Vant3作为移动端组件库里使用率很高的一个库，默认提供的主题色是蓝色（#1989fa）。但真实项目中，UI设计稿的主题色几乎不可能是这个默认值，产品还经常提出夜间模式、多品牌换肤这类需求。这时候就必须对Vant3做主题定制。Vant3官方给出了两条路：一条是基于CSS变量的运行时覆盖，另一条是基于Less变量的构建时覆盖。两条路该怎么选、配置时有哪些坑，这篇文章一次讲清楚。
方案一：使用CSS变量覆盖主题（推荐首选）
Vant3的所有组件样式都基于CSS变量实现，比如按钮的背景色对应--van-button-primary-background，单元格的文字颜色对应--van-cell-text-color。这意味着你完全不需要碰构建工具，直接在全局样式里重新定义这些变量即可生效。这种方式的优点是配置成本极低，而且可以在运行时用JavaScript动态修改变量值，实现实时换肤和暗黑模式。
最简单的做法是在项目的全局样式文件中，针对根选择器重写变量：
:root {
--van-primary-color: #ff6600;
--van-button-primary-background: #ff6600;
--van-cell-text-color: #333333;
}
如果你只希望某个页面局部定制，也可以把变量写在某个容器类名下，作用域会限制在该容器内部，不会影响其他页面。这一点在多主题共存的场景下非常实用。
要动态换肤，只需要操作document.documentElement.style.setProperty即可：
// 切换主题色为红色
document.documentElement.style.setProperty('--van-primary-color', '#ee0a24');
// 切换暗黑模式（Vant3提供了内置的暗黑变量集合）
document.documentElement.classList.add('van-theme-dark');
需要注意的一点：Vant3的暗黑模式变量前缀和普通变量是同一套体系，通过给根元素添加van-theme-dark类名激活。如果你自己在暗黑模式下又覆盖了一遍变量，要注意优先级问题，建议把自己的覆盖写在更具体的选择器下，或者干脆把自定义值也注册成两套，跟随主题类名切换。
方案二：使用Less变量构建时覆盖
如果你的项目本身使用Less，并且希望主题在构建阶段就固化下来，可以在引入Vant3样式源文件时传入自定义变量。Vant3的样式是用Less编写的，核心变量比如@van-primary-color在入口文件中被引用，我们可以在引入前先声明自己的值。
以Vue CLI项目为例，需要借助style-resources-loader或直接修改引入方式：
// main.js 中引入样式源文件
import { createApp } from 'vue';
import Vant from 'vant';
import 'vant/lib/index.less';
// 在vue.config.js中配置样式资源注入
const path = require('path');
module.exports = {
css: {
loaderOptions: {
less: {
lessOptions: {
modifyVars: {
'primary-color': '#ff6600'
},
javascriptEnabled: true
}
}
}
}
};
Vite项目则更简洁一些，通过CSS预处理器配置项传入modifyVars：
/* vite.config.js */
export default {
css: {
preprocessorOptions: {
less: {
modifyVars: {
'primary-color': '#ff6600'
},
javascriptEnabled: true
}
}
}
};
这种方案的优势是定制后的样式直接编译进产物，没有运行时变量查找开销，兼容性也更好（不需要考虑老旧浏览器对CSS变量的支持问题）。缺点也非常明显：主题在构建时就被写死，无法运行时切换，每次换肤都要重新打包。对于需要多主题运营或者夜间模式的App，这条路线基本不适用。
另外一个容易踩的坑：modifyVars里写的变量名必须和Vant源码中定义的变量名完全一致，拼写错误不会报错，只会静默失效。排查时建议直接打开node_modules目录下的vant源码less文件，对照变量名逐个检查。
两种方案怎么选及常见避坑建议
选择标准其实很简单：只要你的项目存在运行时换肤、暗黑模式切换的需求，就选CSS变量方案；如果是传统的单主题项目，且团队已经统一使用Less，两种都可以，CSS变量方案配置更省事，通常作为首选。
以下是实际开发中被反复踩到的一些坑，提前了解能少走很多弯路：
- 样式不生效：最常见的原因是自己的覆盖样式被Vant的默认样式压住了。检查引入顺序，确保自定义样式文件在Vant样式之后引入；必要时提高选择器优先级。
- 变量名写错：Vant3的CSS变量统一以
van-为前缀，比如--van-button-primary-border-color。少写前缀或单词顺序写反都不会报错，只会不生效。 - 暗黑模式闪烁：刷新页面时先亮后暗，是因为主题类名是在JS执行后才加上去的。解决办法是在页面的head里内联一段同步脚本，根据localStorage中存储的主题值提前给html元素添加类名。
- postcss配置冲突：如果项目里配置了postcss-pxtorem或类似的单位转换插件，注意排除node_modules里的Vant样式，否则组件尺寸会被意外缩放。
- 局部覆盖失效：CSS变量存在继承性，写在子容器上的变量可能被更高层的定义覆盖。排查时用浏览器开发者工具的Computed面板查看变量的最终计算值来源。
最后补充一个实用技巧：如果只是想微调个别组件，不必动全局变量，直接用开发者工具选中组件，在Styles面板里过滤出--van-开头的变量，找到对应的那个精准覆盖即可，比翻文档找变量名快得多。把这套思路和避坑清单收藏好，下次定制Vant3主题时基本可以一次通过。