企业官网建设流程全解析

换肤这个需求，放在 uni-app 全端项目里，真不是写几个 CSS 变量就能糊弄过去的。尤其是技术栈还锁在 Vue2 + uView 1.0 的时候，uView 的主题色是编译期直接用 SCSS 变量生成的，运行的时候你想改颜色，它根本不鸟你。我这次做的是一个老项目的“全端动态换肤方案”，覆盖 H5、微信小程序、App 三端，踩了不少坑之后，整理了一套能稳定跑通的实现思路，今天完整拆开讲清楚，给还在 Vue2 + uView 1.0 里挣扎的朋友做个参考。

1. 换肤需求分析与方案选型

1.1 先想清楚：你要做的到底是哪种“换肤”

动手写代码之前，我建议你先问产品经理一个问题：产品要的“换肤”，是固定几套主题皮肤随时切换，还是让用户自定义品牌色，还是单纯跟随系统深浅色？这三者的技术难度完全不同，方案也截然不同。

• 固定几套主题包（比如默认蓝、商务红、暗夜黑），本质上是维护多套 token，切换时替换 token 就行。
• 自定义任意颜色，需要把颜色作为工具变量存储，再通过换肤函数把变量动态注入样式系统，对样式覆盖体系的完整性要求很高。
• 跟随系统深浅色，则要处理系统主题监听、默认值与用户覆盖的优先级，以及变量在不同阈值下的分组。

我这次项目属于“多套固定主题 + 用户可微调品牌色”的混合场景。这个需求一确定，就意味着没法用“预编译多套 CSS 文件打包”的懒人办法，必须引入运行时动态换肤机制。

1.2 为什么绕不开 CSS 变量：三端最小公共交集

先给结论：在 uni-app 的全端环境下，运行时换肤的可行方案里，CSS 变量是目前最优雅的“最小公共交集”。原因很现实，H5 端可以直接操作 document 上的样式表，但小程序端禁止操作 document，App 端还要区分 Vue 页面（WebView 渲染）和 nvue 页面（原生渲染）。

CSS 变量在内联 style 上使用，是微信、支付宝等小程序端和 H5、App Vue 页面都能支持的能力。换句话说，你用<view :style="themeVars">把变量挂在页面根节点上，再在子元素里通过var(--brand-primary)取用，这是当前全端都能跑通的方案。

当然，nvue 是个例外——它原生渲染不认 CSS 变量。如果你的项目必须保留 nvue 页面，就得在方案设计层面给 nvue 留一条“不换肤”的退路，或者干脆避免使用 nvue。我在这个项目里直接把之前遗留的 nvue 页面改回了 vue 页面，一劳永逸。

1.3 方案对比：为什么不用 SCSS 变量、类切换或动态加载 CSS

这里放一张对比表，帮大家快速理解几种可选方案的取舍。

动态插入 style 标签的方案，我只建议在纯 H5 项目里用。只要项目带了小程序端，就必须回到 CSS 变量这条路上来，没有第二条路可走。

2. 主题系统的工程化搭建

2.1 统一维护主题变量：一份 token 管全端

换肤方案要可维护，第一步是把散落在页面里的颜色全部收拢成“主题 token”。这里不是让你手动去每个页面改，而是在项目里建立一份theme/tokens.js，保存所有主题的基础 token。

比如一个主题对象长这样：

// theme/tokens.js export const lightTheme = { '--brand-primary': '#2979ff', '--brand-primary-light': '#5aa3ff', '--brand-primary-dark': '#0f5fd6', '--brand-success': '#19be6b', '--brand-warning': '#ff9900', '--brand-error': '#fa3534', '--bg-page': '#f8f8f8', '--bg-card': '#ffffff', '--text-main': '#303133', '--text-sub': '#909399', '--border-color': '#e4e7ed' } export const darkTheme = { '--brand-primary': '#3d8bff', '--brand-primary-light': '#6bb1ff', '--brand-primary-dark': '#155ed4', '--brand-success': '#22c57a', '--brand-warning': '#ffb340', '--brand-error': '#ff5b5b', '--bg-page': '#121212', '--bg-card': '#1e1e1e', '--text-main': '#e5e5e5', '--text-sub': '#909399', '--border-color': '#3a3a3a' }

这里有两个关键点。

key 一定要用--开头的 CSS 变量名，方便后续直接通过 style 绑定渲染到节点上，不用再做一层转换。

变量命名按“语义化”而不是按“色值化”。比如不要叫--blue，而要叫--brand-primary。这样深色模式下把品牌色加深，业务代码不用动。我见过一个项目把变量名直接叫--theme-color-1，后来设计师一调色，全组人对着变量表猜含义，维护成本很高。

2.2 解决 uView 1.0 的“编译期色值”问题

uView 1.0 的默认主题色是在uview/theme.scss里通过$u-primary这类 SCSS 变量定义的，编译后直接变成具体的色值写进样式里。结果就是：你运行的时候再改 CSS 变量，对 uView 组件里的颜色根本不起作用。

我当时的应对思路是给 uView 组件织一张“覆盖网”，分两层。

第一层，能用组件属性解决的优先用属性。比如u-button的custom-style、u-tag的color属性，这类官方预留的覆盖入口最稳妥，小程序端也不存在样式隔离问题。能用属性解决的就不要去碰 CSS。

第二层，属性覆盖不到的地方，再写全局覆盖样式，用 CSS 变量替换掉写死的色值：

// theme-override.scss .u-btn--primary { background-color: var(--brand-primary) !important; border-color: var(--brand-primary) !important; }

需要注意的是，小程序端的自定义组件样式默认隔离，全局样式并不一定能穿透到组件内部。如果某个组件的内部结构无法用属性覆盖，我会优先自查 uView 1.0 是否暴露了针对该结构的插槽或 props，而不是盲目堆!important。真正必须写 CSS 覆盖的地方，建议集中在theme-override.scss里维护，方便日后升级 uView 时快速排查。

2.3 在 Vue2 / uni-app 里全局注入主题状态

因为项目是 Vue2 技术栈，状态管理我用 Vuex 来做。主题模块的关键在于：初始化时从本地缓存里同步读取上次选择的主题，而不是等页面渲染完再异步恢复。

// store/modules/theme.js import { lightTheme, darkTheme } from '@/theme/tokens.js' const state = { // 注意：这里必须同步初始化，不能写在 onLaunch 里异步读取 themeName: uni.getStorageSync('themeName') || 'light', systemTheme: 'light', customColor: uni.getStorageSync('customColor') || '' } const getters = { isDark(state) { // 用户手动选择优先，其次跟随系统 if (state.themeName === 'system') { return state.systemTheme === 'dark' } return state.themeName === 'dark' }, activeTheme(state, getters) { const base = getters.isDark ? darkTheme : lightTheme if (!state.customColor) return base return { ...base, '--brand-primary': state.customColor } } } const mutations = { SET_THEME_NAME(state, name) { state.themeName = name uni.setStorageSync('themeName', name) }, SET_SYSTEM_THEME(state, theme) { state.systemTheme = theme }, SET_CUSTOM_COLOR(state, color) { state.customColor = color uni.setStorageSync('customColor', color) } } const actions = { setTheme({ commit }, { name, color }) { if (name) commit('SET_THEME_NAME', name) if (color) commit('SET_CUSTOM_COLOR', color) } } export default { namespaced: true, state, getters, mutations, actions }

主题状态必须同步初始化，这一点特别重要。在 Vue2 + uni-app 里，App.vue 的onLaunch和首屏页面的渲染时机非常接近，如果启动时先渲染默认主题再异步读取 storage，用户每次打开小程序都会先看到一次错误主题的闪烁，很掉档次。把uni.getStorageSync直接放在 state 定义处，就是为了从源头掐掉这个问题。

3. 核心实现：换肤逻辑与全端样式切换

3.1 换肤状态管理与切换函数

在页面或公共组件里，切换函数只需要提交 action：

// utils/theme.js import store from '@/store/index.js' export function switchTheme(name, color) { store.dispatch('theme/setTheme', { name, color }) }

如果项目里不是每个页面都安装 Vuex 的 mapGetters，也可以用uni.$emit事件广播主题变化，再由根组件统一监听并更新变量。不过我的经验是：既然已经引入了 Vuex，直接用mapGetters('theme', ['activeTheme'])最省心，响应式天然生效，页面切后台再回来也不会丢失状态。

3.2 各端样式挂载方式：一个根组件搞定

全端换肤的核心其实就在这一小段代码里。我搭了一个ThemeRoot.vue组件，替换掉原本每个页面的最外层 view：

<!-- components/ThemeRoot.vue --> <template> <view class="theme-root" :style="themeVars"> <slot /> </view> </template> <script> import { mapGetters } from 'vuex' export default { name: 'ThemeRoot', computed: { ...mapGetters('theme', ['activeTheme']), themeVars() { // 这里把主题 token 转成内联 style 的对象格式 return this.activeTheme } } } </script> <style lang="scss" scoped> .theme-root { min-height: 100vh; background-color: var(--bg-page); color: var(--text-main); } </style>

在页面里这样用：

<template> <theme-root> <!-- 页面原有内容 --> </theme-root> </template> <script> import ThemeRoot from '@/components/ThemeRoot.vue' export default { components: { ThemeRoot } } </script>

把主题变量挂在页面根节点的内联 style 上，子元素所有使用var(--xxx)的样式都会自动跟着响应。H5 端、微信小程序端、App 的 Vue 页面端，这一套都能生效。我自己实测下来，微信开发者工具、真机和浏览器表现一致。

有一点要提醒：不要图省事在App.vue里给全局 view 设置变量。uni-app 的页面结构在 App.vue 外面还有一层，变量作用域覆盖不全会导致部分节点取不到。挂在每个页面自己的根节点，是作用域和性能的平衡点。

3.3 织一张“覆盖网”：uView 组件主题覆盖清单

uView 1.0 组件很多，但实际开发中用得多的也就按钮、标签、单选、复选、开关、加载、徽标这些。下面是我项目里整理过的覆盖清单，供参考。

// theme-override.scss // 按钮 .u-btn--primary { background-color: var(--brand-primary) !important; border-color: var(--brand-primary) !important; } .u-btn--primary.u-btn--hairline { color: var(--brand-primary) !important; background-color: transparent !important; } .u-btn--primary.u-btn--plain { color: var(--brand-primary) !important; background-color: transparent !important; } // 标签 .u-tag--primary { background-color: var(--brand-primary) !important; } // 徽标 .u-badge { background-color: var(--brand-primary) !important; } // 单选/复选选中态 .u-radio__icon--checked { border-color: var(--brand-primary) !important; background-color: var(--brand-primary) !important; } .u-checkbox__icon--checked { border-color: var(--brand-primary) !important; background-color: var(--brand-primary) !important; } // 开关激活态 .u-switch--on { background-color: var(--brand-primary) !important; }

这份清单不是一次性写完的。我是让测试同学在真机上把常用页面过一遍，哪里还是旧色就补哪里，来回三轮才收敛。比较意外的是u-switch，它的激活态类名在不同版本里有差异，覆盖时一定要以你锁定的 uView 版本实际渲染出来的类名为准，不要照抄网上的旧写法。

3.4 深色模式的联动处理

如果产品要求“跟随系统深浅色”，可以接入系统主题检测和变化监听：

// utils/theme.js function getSystemTheme() { try { const info = uni.getSystemInfoSync() return info.theme || 'light' } catch (e) { return 'light' } } export function watchSystemTheme() { // 微信小程序支持主题变化监听 if (uni.onThemeChange) { uni.onThemeChange((res) => { store.dispatch('theme/setTheme', { name: 'system' }) store.commit('theme/SET_SYSTEM_THEME', res.theme) }) } }

我的建议是主题状态分成“用户选择”和“系统主题”两层：用户选了“跟随系统”时，展示层用系统主题对应的 token；用户手动选了具体主题后，以用户选择为准。每次切换都同时把选择写入 storage，下一次冷启动才能保持一致。

这里要注意一个边界：用户手动切了暗黑，然后系统主题从暗黑切到浅色，此时要判断用户有没有指定过主题。如果用户一直停在“跟随系统”状态，就跟着系统变；如果用户手动选了，就尊重用户选择，直到用户再次切回“跟随系统”。

4. 首屏闪烁、性能与工程细节

4.1 首屏闪白的根因与三端对策

换肤方案上线后，最容易挨骂的就是首屏闪白：用户上次选了深色，这次打开却先闪一下浅色，观感极差。

H5 端的对策最粗暴也最有效：在index.html里内联一段脚本，在 uni-app 框架启动前，先从 localStorage 读出主题 token，直接写入document.documentElement.style：

<script> (function () { try { var saved = localStorage.getItem('themeVars') if (saved) { var vars = JSON.parse(saved) var style = document.documentElement.style Object.keys(vars).forEach(function (key) { style.setProperty(key, vars[key]) }) } } catch (e) {} })() </script>

小程序端的 render 阶段在业务代码之前，没法塞自定义脚本，唯一的办法是“同步初始化”。前面在 Vuex state 里用uni.getStorageSync初始化主题，就是为这一步服务的。只要首次渲染拿到的 store 数据就是目标主题，页面不会闪。

App 端如果走的是 WebView 渲染的 Vue 页面，可以直接复用 H5 的思路；如果页面本身能接受短暂 loading，用启动页挡住闪烁也是一种兜底策略。

4.2 切肤以后“旧色残留”的排查

我在开发中碰到过一次诡异现象：主题切换后，大部分页面都正常，唯独从“我的”页面返回到首页时，首页部分颜色还是旧主题。排查后发现是首页某个区块的样式写在了组件的scoped样式里，使用了一个不经过 CSS 变量的固定色值，导致这个区块不会跟随主题更新。

这类问题的排查思路很简单：全局搜索项目里所有scoped样式中的十六进制颜色值，把业务色值统一替换成语义化的var(--xxx)。替换的时候注意别一把梭，边框、阴影、渐变这些辅助样式也要纳入变量体系，否则会出现“主色对了、边框还是旧色”的割裂感。

再补充一个排查技巧：微信开发者工具的“WXML 面板”里可以直接查看节点计算后的 style，如果发现某个节点颜色没变，优先看它的父节点链上有没有--brand-primary这个变量。从根节点往下捋，基本能定位到是哪一层丢了变量。

4.3 避免一次性全量样式更新的性能坑

CSS 变量更新本身是 O(1) 的操作，但如果页面复杂度高、变量数量多，切换一多也会有性能压力。我的经验是：页面根节点的themeVars只挂“当前主题和默认主题的差异部分”，不要每次切换都全量输出几十个变量。

具体做法是在 getter 里做一次 diff：

// store/modules/theme.js const diffVars = (base, target) => { const result = {} Object.keys(target).forEach((key) => { if (base[key] !== target[key]) { result[key] = target[key] } }) return result } const getters = { themeVars(state, getters) { // baseLight 是浅色主题，作为基准 return diffVars(baseLight, getters.activeTheme) } }

这样做的好处是：浅色主题下如果变量值和默认值一致，根节点内联 style 里就只有几个 key，省去了不必要的渲染 diff，也减少了小程序端 setData 的数据量。实测在低端 Android 机上，切主题的掉帧明显减少。

5. 常见问题排查与实战心得

5.1 小程序端样式不生效的三种情况

CSS 变量方案在小程序端踩坑最多的是旧版本基础库。如果发现某些 iPhone 上变量不生效，先查基础库版本，低于 2.9.0 的需要在文档里标注最低支持版本，或者干脆放弃对这些低版本用户做动态换肤，回退成默认主题。

第二种情况是变量作用域丢失。检查页面最外层是不是正确包了ThemeRoot，如果某些页面没有包，那些页面的变量就只有系统默认值，主题切换自然失效。可以用一个全局 mixin 统一注入：

// mixins/themeRoot.js export default { computed: { ...mapGetters('theme', ['themeVars']) } }

在页面根节点上手动绑定:style="themeVars"，至少保证每个页面都有变量入口。虽然不如 ThemeRoot 组件干净，但对老项目改动量更小。

第三种情况是 uView 组件内部结构的样式隔离。全局theme-override.scss覆盖不上时，优先去看 uView 组件文档有没有暴露custom-style之类的属性，有就用属性传变量，没有就老实提 issue 或用自定义组件替代。别在!important上死磕，小程序端自定义组件的样式隔离机制决定了这条路经常走不通。

5.2 同一份代码，H5 正常、App 颜色不对

这类问题九成出在 App 端渲染上。App 端 vue 页面默认是 WebView 渲染，CSS 变量理论上支持，但如果项目里混用了 nvue 页面，nvue 页面就是不认 CSS 变量的。遇到 nvue 页面定制颜色，只能单独写一套条件编译样式，或者调整业务逻辑让 nvue 页面以中性色为主，减少对主题色的依赖。

如果你在 App 端的 vue 页面上也发现变量不生效，先确认 HBuilderX 的编译版本，某些自定义组件在 App 端会被特殊处理，必要时升级到较新的编译器再测一轮。我遇到过同一个组件在 H5 正常、App 上 CSS 变量值变成空字符串的情况，最后是升级 HBuilderX 解决的，大概率是编译器对自定义属性的序列化处理有 bug。

5.3 顺手记录两个同技术栈高频问题

开发过程中还碰到过两个跟换肤无关、但同样让人头疼的问题，顺手记录一下。

第一个是 HBuilderX 内置浏览器或模拟器偶尔报uni-app network: unavailable。排查思路是先看系统代理是否正常，再重启 HBuilderX，或者干脆用真机预览绕过本机网络问题。多数情况下是调试器缓存导致的假故障，不影响真机运行。

第二个是 App 打包加固后无法安装或签名失效。加固后的 APK 会丢失原签名，需要在加固完成后用原有 keystore 重新签名，否则安装时会报签名不一致。这里提一句，算是给准备走应用市场发布流程的朋友避个坑。

最后再分享一个小经验。换肤方案上线后，最容易被忽略的不是技术，而是设计侧的合作。建议在需求初期就让设计师把深色主题和自定义主题色的变量规范定下来，而不是等前端切完了再一张一张核对效果图。我这次就是因为设计规范滞后，来来回回改了四版 token，白白多花了一周时间。先把 token 表和组件覆盖清单当成项目文档的一部分维护，后面所有页面新开发都直接引用变量，换肤这条路才算真正走通了。