企业官网建设流程全解析

做前端的人应该都有这种体会：组件库的功能迭代到一定阶段，真正让人头疼的往往不是新增组件，而是主题定制和暗色模式适配。组件一多，颜色、圆角、边框、字号散落在各个 style 文件里，想换肤就得全局替换，改一处崩三处。我在梳理 TinyVue 这套组件库的主题系统时，发现它把"设计变量、运行时状态、组件样式"三者之间的边界理得非常清楚，而这恰恰是很多自研组件库做不到或者懒得做的地方。

这篇是"探索 TinyVue 组件库系列之主题系统"的第一篇，主线就是主题系统的架构设计。我会从架构层面拆清楚几件事：主题系统为什么要分层设计、Design Token 是怎么流转成组件样式的、主题包在工程上是如何组织的、运行时切换主题又依赖了什么机制。后面几篇再逐个深入具体的实现细节和踩坑案例。

如果你正在维护公司内部的组件库，或者正准备给现有前端项目做一套可配置的主题方案，这篇文章应该能给你一张可以直接对照的架构草图。

1. 为什么主题系统最容易成为组件库的"烂尾楼"

先说个很现实的现象：绝大部分组件库在最开始是不设计主题系统的。第一版组件通常直接写死颜色，比如color: #1476ff、background: #f5f5f5，等组件数量超过三十个，产品突然说要支持暗色模式、要支持品牌换肤，工程侧才开始补主题能力。这个阶段最常见的做法是全局搜索替换颜色，或者把所有变量抽到一个 SCSS/LESS 文件里重新编译。短时间看是解决了，但架构层面的问题并没有消失。

1.1 组件库主题问题的三个层次

我把平时踩过的主题相关需求归纳成三个层次，这也是判断一套主题系统设计得好不好的试金石：

• 换肤层：整体替换品牌色、背景色、文字色，让组件库适配不同客户或者不同产品线的视觉风格。
• 模式层：支持亮色 / 暗色 / 高对比度这类全局显示模式，而且是要在运行时动态切换的，不是刷新页面才生效。
• 定制层：某个业务场景下局部覆盖个别组件样式，比如把某个页面的按钮改成渐变色，不能影响全局其他页面。

这三个层次对架构的要求完全不同。换肤层只要保证"变量别写死"，模式层要求"变量能被运行时整体替换"，定制层则要求"变量作用域可控制"。很多组件库做到第一层就停在原地，暗色模式全靠暴力和重要修饰符去堆，最后维护成本全部后置到业务侧。

1.2 传统主题方案为什么扛不住

早年比较主流的方案有两种：一种是维护多套完整的样式文件，default.css、dark.css、brand-a.css，切换时整体替换样式表引用；另一种是基于 SCSS 变量编译出多套产物，构建时通过defineConfig之类的配置切换主题变量。

这两种方案的问题非常类似，本质上是把"主题"等同于"整套静态样式"。第一，增量成本高，每加一套主题基本等于把组件样式重新生成一遍，文件体积成倍上涨；第二，运行时切换能力弱，SCSS 变量在编译期就已定型，想让用户不刷新页面就换肤，只能额外加载另一套 CSS 再覆盖；第三也是最麻烦的，一旦某个组件样式里混入了硬编码值，排查起来如同大海捞针。

所以我一直认为，一套能长期运转的组件库主题系统，核心不是"怎么定义几组漂亮的颜色变量"，而是"主题变化时，有哪些路径能确保样式一定跟着变"。TinyVue 的主题系统之所以值得拆解，就是因为在这一点上它把变量链路打通得很彻底。

1.3 TinyVue 主题系统的设计出发点

TinyVue 是 Vue 3 / Vue 2 都支持的开源组件库，主题系统用的是业内现在比较认可的方案：Design Token 体系 + CSS Variables 运行时覆盖。这套组合的优点在于，主题系统和组件实现是解耦的：

• 组件样式里永远只写var(--tv-color-primary)这样的 CSS 变量，不关心这个变量的值来自哪里；
• 主题包只负责输出一套 CSS 变量定义，亮色、暗色、自定义主题都是不同的一组变量；
• 切换主题时，只需要替换根节点上的变量集合，组件样式自动跟着变，不需要重新加载组件样式。

这样设计之后，"换主题"在运行时变成了一个非常轻量的操作：改数据，不改组件。下面我把这条链路从底层到上层完整拆开讲。

2. 三层链路拆解：Design Token 如何一路变成组件样式

TinyVue 主题系统在架构上大致分为三层：基础 Token 层、语义 Token 层、组件样式消费层。听起来有点学术，但拆开看其实就是一条流水线：先有基础原料，再加工成中间品，最后组件拿中间品组装。

2.1 基础 Token 层：先定"调色盘"，再谈其他

基础 Token 是主题系统最底层的那批原始变量，类似设计师常说的 Design Token 里的 primitive token。它们通常不关心业务语义，只描述客观的视觉取值。比如：

• 品牌色系下的几个梯度色值：一级蓝、二级蓝、三级蓝；
• 中性色阶：从纯黑到纯白之间的一整条灰阶；
• 字体族、字号梯度、行高；
• 间距梯度、圆角梯度、阴影梯度。

这一层的特点是与业务无关、与组件无关，理论上可以被任何一套主题复用。在设计架构时，基础 Token 应该具备"全集"的概念，也就是说无论你未来要做多少套主题，取的都应该是同一批基础变量的不同取值。

2.2 语义 Token 层：组件不直接认颜色，只认语义

如果让组件样式直接引用基础 Token，比如color: var(--blue-500)，那暗色模式下所有"蓝色"都要被替换一遍，你根本分不清哪个蓝是主色调，哪个蓝只是分割线。所以主题系统必须有一层语义 Token，把"组件场景"和"具体颜色取值"隔开。

语义 Token 的命名逻辑是按用途走，而不是按色值走。比如：

同一套语义 Token，在亮色和暗色模式下取值完全不同，但对组件来说，它只需要认--tv-color-text-primary这个"名字"，不需要知道具体是深灰还是浅灰。这就是语义 Token 层的核心价值：把视觉决策从组件实现中剥离出去。

2.3 CSS 变量映射与组件样式消费

有了语义 Token，剩下的就是如何把它们变成浏览器能识别的变量。TinyVue 的架构在这里选择了 CSS Variables 作为载体，原因主要有两个：

一是 CSS 变量天然支持运行时更新。你可以在:root上声明变量，然后在任意时刻通过document.documentElement.style.setProperty('--tv-color-primary', '#ff6600')改变它的值，页面上所有消费这个变量的元素会立即更新，无须触发重新渲染。

二是 CSS 变量具有继承性和局部覆盖能力。你可以在某个容器节点上临时覆盖一组变量，这个容器内所有组件都会按照新变量渲染，其他区域不受影响。这个特性直接支撑了前面提到的"局部定制"需求。

组件样式消费层就比较直接了。TinyVue 组件在编译后的 CSS 里大量使用var()函数，比如：

.t-button--primary { background-color: var(--tv-color-primary); border-color: var(--tv-color-primary); }

这套代码不用区分亮色还是暗色，不管根节点上的变量值是什么，它会自行适应当前主题。

2.4 一个按钮在链路中的完整旅程

把三层链路串起来看，一个按钮从设计到最终渲染大致是这样的：

1. 设计师从基础色板中选取品牌主色，定义语义 Token：主色、悬停色、按压色、禁用色。
2. 开发者把这些语义 Token 写入主题包，编译成 CSS 变量声明，挂载在:root上。
3. 按钮组件样式通过var()引用相应语义变量。
4. 用户切换暗色主题时，主题系统替换根节点上的变量合集，按钮样式随后自动更新。

我拿实际的开发经验强调一句：排查主题问题时，也一定按照这条链路逐层检查。先看变量值对不对，再看组件样式有没有真的引用变量，最后看变量挂载在哪个节点上。绝大多数"主题没生效"的问题，定位到最后都落在这三件事之一。

3. 主题包 @opentiny/vue-theme 的工程结构

聊完原理，就该落到工程上了。TinyVue 的主题能力不是散落在各个组件里的，而是集中在名为@opentiny/vue-theme的独立包中。把主题独立成包，这个决定本身就很有价值：主题的开发、构建、发布都不需要跟着组件库主包走，业务团队甚至可以自行 fork 一份，定制完内部发布。

3.1 主题包里到底放了什么

从工程角度看，主题包的源码通常会包含几类内容：

• 变量定义源码：基础 Token 和语义 Token 的源文件，以 SCSS 变量或者 JSON 的形式存在。
• 组件样式文件：组件样式本身并不在组件包里直接写死，而是作为主题包的一部分输出。这样组件包保持"无样式"或者"极简样式"状态，主题包决定最终外观。
• 构建脚本：负责把 Token 源码编译成可供浏览器加载的 CSS 产物。
• 暗色主题或自定义主题的增量覆盖：通常是一份专门针对暗色模式重新赋值的变量集合。

很多人第一次打开主题包时会觉得文件又多又杂，其实它的组织逻辑就是刚才说的三层链路：基础 Token、语义 Token、组件样式三者分区存放，再通过构建串联起来。

3.2 一套 source 多套主题的构建思路

这里有一个架构上比较关键的设计：并不是为亮色主题和暗色主题分别维护两套完整的组件样式。组件样式只用写一份，主题之间的差异完全靠变量层去消化。

构建时可以这样理解：

• 默认主题：输出一套完整的组件样式 + 亮色语义变量；
• 暗色主题：不重新输出组件样式，只输出一套覆盖型的暗色语义变量；
• 自定义品牌主题：同理，只输出自定义变量集。

这种做法在产物体积上很占优势。暗色主题通常只是一个几十 KB 的变量覆盖文件，不需要把几百 KB 的组件样式再生成一遍。运行时的加载策略也可以做成"默认主题随组件库一起加载，暗色变量文件在用户切换时按需加载"。

3.3 按需引入场景下的主题配套

现在很多项目都会用unplugin-vue-components或者vite-plugin-tinyvue做组件按需引入，主题包也要配合这种使用方式。实践中有两个容易踩的点：

第一，按需引入组件时，样式是按组件拆分的，主题变量文件必须保证在组件样式之前注入。如果变量声明晚于组件样式加载，某些浏览器的级联顺序可能会导致变量暂未生效。

第二，暗色模式变量覆盖文件如果体积不大，建议直接在入口文件里全量引入，不需要做按需分析。因为变量文件本身是全局性质的，拆太细反而增加加载复杂度。

我在一个 Vite 项目里做过一次对比，全量引入主题包和按需引入组件时主题文件的加载体积差异通常不大，主要收益来自组件样式本身被 tree-shaking 掉，主题变量部分反而是常量开销。

4. 运行时主题切换是怎么做到的

主题系统的架构设计得再好，最终都要回答一个问题：用户点一个开关，页面如何从亮色变成暗色？这一章我们从机制上拆解运行时切换的原理和工程细节。

4.1 CSS 变量方案天然支持运行时切换

如果是传统 SCSS 编译方案，运行时要换主题基本只能靠重新加载样式文件或者用脚本去覆盖成百上千条规则，性能和可维护性都堪忧。而 CSS 变量方案在机制上就把这个问题解决了：组件样式引用的是变量名，变量值变化了，所有引用点自动更新。

TinyVue 这种架构下，切换主题的最核心行为就是更新根节点上的变量集合。方式可以无外乎两种：

// 第一种：整体替换主题类名 document.documentElement.setAttribute('data-theme', 'dark') // 第二种：编程式覆盖某个变量 document.documentElement.style.setProperty('--tv-color-primary', '#ff6600')

第一种适合切换预设主题，第二种适合做局部动态调整。两者配合时，CSS 的层叠规则会保证内联 style 的优先级更高，这就是为什么局部覆盖也有机会生效。

4.2 亮色暗色两套主题的挂载方式

从架构设计上看，预设主题的变量集合最好隔离挂载，避免互相污染。一般做法是：

• 亮色主题变量默认挂在:root上，作为全局兜底；
• 暗色主题变量挂在[data-theme='dark']这个选择器下；
• 切换时只改变html节点的>:root { --tv-color-primary: #00b96b; --tv-color-primary-hover: #27c68b; --tv-color-primary-active: #00945a; }

  这几乎是零成本的定制方式。它不要求你 fork 主题包，也不要求你重新构建任何文件。但有两个前提：

  • 你要知道一个组件到底消费了哪些语义变量，否则会漏改；
  • 你要把变量命名规范完整地沉淀到团队文档里，否则后面的人只能靠猜。

  我的建议是，这种量级的定制适合"临时方案"或者"验证性改动"。一旦涉及品牌级的多组件一致性调整，还是应该走下面的 Token 配置流程。

  5.2 中量级：基于 Token 配置生成主题

  如果是正经的品牌主题定制，正确的做法是在源码的 Token 配置层修改，然后走构建生成一套主题产物，而不是在业务代码里层层覆盖。

  具体思路是：fork 一份主题包源码，维护一套品牌 Token 配置，然后运行主题包提供的构建命令，产出独立的主题 CSS 文件。这个过程和改业务样式完全不同，它是在"主题系统内部"做定制，后续变量升级、暗色模式适配都会自动继承主题系统的架构能力。

  这里分享一个项目实践里比较有用的经验：品牌 Token 配置尽量基于基础 Token 引用，而不是直接写死色值。比如定义主色时，可以写成"品牌色的一号梯度"，这样暗色模式适配时系统知道主色的色相和亮度关系，能够自动推导出暗色下的主色，而不是暗色主题里还残留着亮色品牌色的突兀产物。

  5.3 组件级局部定制怎么处理

  局部定制的需求通常来自业务页面，比如某一块营销区域按钮要做成渐变。这种场景既不应该改全局主题，也不应该给组件加各种状态类型，正确的做法是利用 CSS 变量的局部覆盖能力：

  <template> <div class="marketing-block"> <tiny-button type="primary">立即购买</tiny-button> </div> </template> <style scoped> .marketing-block { --tv-color-primary: linear-gradient(135deg, #ff6a00, #ff2d55); } </style>

  容器上的变量覆盖只影响这个容器内的组件，外面的页面完全不受干扰。要是在 Vue 的 scoped 样式里发现覆盖不生效，通常是因为变量定义在容器上，而组件内部消费变量的节点层级较深时，继承仍然有效，但如果组件把变量值应用到了定位脱离容器的弹层或浮层上，就需要配合 Teleport 的目标节点处理变量作用域。这一点做组件库运维的人应该都深有体会。

  6. 主题系统的踩坑记录与定位思路

  最后分享几个我在使用 TinyVue 主题系统过程中真实踩过的坑，以及一套可以复用的排查思路。这些内容不涉及特别高深的技术，但实操价值很高。

  6.1 主题没生效，先查这四处

  遇到"我改了变量但页面没反应"的情况，不要急着怀疑组件库有 bug。按下面四个节点定位，90% 的问题都能找到：

  1. 变量命名是否拼错：TinyVue 的语义变量很多，--tv-color-text-primary和--tv-color-text-secondary只差一个单词，复制粘贴时稍不注意就错。
  2. 变量挂载的节点对不对：如果变量挂在了某个子容器上，而组件通过 Teleport 渲染到了 body 下，变量就继承不到。
  3. 阴影 DOM 作用域：使用组件库内置组件一般不会遇到，但如果自己封装了 Shadow DOM，外部 CSS 变量默认无法穿透，需要显式继承。
  4. 顺序和优先级问题：全局业务样式如果用了更高优先级的写法覆盖了主题变量，优先排查业务样式，而不是主题系统。

  6.2 暗色模式下组件"五彩斑斓"的排查链路

  暗色模式最常见的症状是：切换主题后，大部分组件正常，但个别组件颜色是错的，比如按钮还是亮色主题的蓝色，文字却已经变白。这种情况十有八九是组件样式里存在硬编码颜色。

  排查路径是这样的：

  • 在浏览器 DevTools 里选中出问题的元素，看 Computed 样式；
  • 如果是某个具体色值，往上找这条规则来自哪个样式文件；
  • 重点检查是不是有业务样式、第三方 UI 库样式或者某个旧版本组件样式的残余；
  • 如果确认是组件样式里的硬编码，记录下来反馈给组件库维护方，同时在应用层先覆盖处理。

  我自己处理这类问题时，还会做一次全站扫描：在暗色主题下，利用控制台脚本遍历所有元素的 computed 样式，筛出没有引用 CSS 变量且与预期色板不一致的颜色。这个脚本虽然不优雅，但在排查几百个组件时效率很高。

  6.3 微前端或 iframe 场景的变量隔离

  微前端架构下，每个子应用可能都有自己的html根节点。如果两个子应用都往各自的根节点挂了一套主题变量，而公共组件又是共享的，就会出现"这个子应用是暗色，另一个子应用却是亮色"的割裂感。

  架构层面能落地的方案是：由主应用统一管理一套主题变量，子应用不单独初始化主题，只消费主应用注入的变量。如果你没法改动子应用的初始化逻辑，至少约定一个全局主题事件，让所有子应用监听同一个主题状态源，各自更新根节点变量。iframe 场景同理，父页面可以通过postMessage通知 iframe 内的页面切换主题，避免两边状态各跳各的。

  6.4 和第三方样式打架的处理

  项目里几乎不可能只用一个组件库，TinyVue 的变量体系和其他 UI 库的样式产生冲突时，通常表现为两类问题：一类是全局选择器被其他库的变量覆盖；另一类是两者都用:root声明变量，但命名不同，导致互相叠加时出现视觉混乱。

  我的处理原则是：核心业务页面尽量统一使用一套组件库的风格变量，非必要的第三方库样式按需引入，不要整包引入。如果确实需要混用，给 TinyVue 的主题变量加上统一前缀并锁定挂载作用域，这是它在命名层面天然支持的。遇到优先级冲突时，优先用作用域隔离解决，不要靠!important硬压，否则后续维护就是给自己埋雷。

  整套主题系统的架构梳理下来，我最大的体感是：TinyVue 没有把主题当作"一堆好看的颜色变量"，而是真正把它当成了一条从设计侧到运行时的完整链路来设计。组件不感知主题、主题不耦合组件、切换只发生在变量层，这三句话基本概括了它的核心思想。

  如果你在自己的组件库里也想引入这套架构，不用一上来就全盘照搬。可以先从语义 Token 层开始，把硬编码颜色全部替换成语义变量，再逐步引入 CSS 变量机制，最后再考虑按需加载和暗色模式。架构的收益是随着规模增长才逐步放大的，早期越早打好基础，后期切主题就越轻松。下一篇我会继续沿着主题系统的实现深入，重点讲 Token 配置和构建产物的细节，到时候见。