手把手教你实现高可定制化的前端主题系统

先上代码：主题切换到底怎么搞

别扯什么 CSS 变量原理了，我直接给你一套亲测能跑通的方案。这玩意儿我在三个项目里用过，包括一个后台管理系统和两个对外站点，基本没翻车。

核心思路就一个：用 CSS 自定义属性（也就是 CSS variables）做主题变量，然后通过 JS 动态替换根元素上的变量值。别整那些花里胡哨的 SCSS 编译多套 CSS 的老办法，维护起来要命。

来看最简可运行版本：

:root {
  --primary-color: #3b82f6;
  --bg-color: #ffffff;
  --text-color: #1f2937;
}

[data-theme="dark"] {
  --primary-color: #60a5fa;
  --bg-color: #111827;
  --text-color: #f9fafb;
}

body {
  background-color: var(--bg-color);
  color: var(--text-color);
  transition: background-color 0.3s, color 0.3s;
}

function setTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem('theme', theme);
}

// 初始化时读取本地存储
const savedTheme = localStorage.getItem('theme') || 'light';
setTheme(savedTheme);

就这么点代码，主题切换就能跑起来。按钮触发 setTheme('dark') 或 setTheme('light') 就行。我建议直接这么干，别折腾 webpack 插件或者 runtime 编译，除非你真有动态加载主题包的需求。

这个场景最好用：支持用户自定义颜色

有些产品要求运营能自己改主色调，比如把蓝色换成紫色。这时候光靠预设的 light/dark 不够，得允许传入任意色值。

我的做法是：除了预设主题，额外提供一个 custom 模式，把颜色存在 localStorage 里。

function applyCustomTheme(colors) {
  const root = document.documentElement;
  Object.entries(colors).forEach(([key, value]) => {
    root.style.setProperty(--${key}, value);
  });
  localStorage.setItem('customColors', JSON.stringify(colors));
  document.documentElement.setAttribute('data-theme', 'custom');
}

// 使用示例
applyCustomTheme({
  'primary-color': '#8b5cf6',
  'bg-color': '#faf5ff',
  'text-color': '#5b21b6'
});

注意这里直接操作 style.setProperty，而不是改 class。因为自定义颜色没法提前写死在 CSS 文件里。这种方式灵活，但要注意：别忘了给默认 fallback，万一用户清了 localStorage，页面不能白屏。

所以初始化逻辑得加强一下：

function initTheme() {
  const savedTheme = localStorage.getItem('theme');
  if (savedTheme === 'custom') {
    const savedColors = localStorage.getItem('customColors');
    if (savedColors) {
      applyCustomTheme(JSON.parse(savedColors));
      return;
    }
  }
  // 如果 custom 数据丢了，回退到 light
  setTheme(savedTheme || 'light');
}

踩坑提醒：这三点一定注意

我在这上面栽过不止一次，列几个血泪教训：

• transition 别加在 :root 上：很多人习惯在 body 或 html 上加 transition，但如果你在 :root 上直接设置 transition，会导致所有使用 var() 的地方都触发动画，包括图标、边框等，性能很差。只给真正需要过渡的元素加，比如 body、header 这些。
• 第三方组件库的颜色覆盖要小心：像 Element Plus、Ant Design 这类库，它们自己的 CSS 变量命名和你的可能冲突。我的做法是：在你的主题变量前加个前缀，比如 --app-primary-color，避免污染全局。如果必须覆盖组件库样式，单独写一段 scoped 的 CSS 覆盖规则。
• 服务端渲染（SSR）时别忘同步主题：如果你用 Next.js 或 Nuxt，用户首次加载时 JS 还没执行，页面会闪一下默认主题。解决办法是在服务端根据 cookie 或 user-agent 预判主题，或者在 _document.js 里注入内联脚本提前设置 data-theme。不过说实话，我大多数项目都是 CSR，这问题不大，但上线前一定要测首屏。

高级技巧：动态生成主题色系

有时候客户不仅要改主色，还要自动算出 hover、active、disabled 状态的颜色。这时候可以引入色彩工具库，比如 color 或 tinycolor2。

我试过几种方案，最终觉得在客户端动态计算最省事——毕竟主题切换本来就是前端行为。

import Color from 'color';

function generateColorPalette(baseColor) {
  return {
    'primary-color': baseColor,
    'primary-hover': Color(baseColor).lighten(0.1).hex(),
    'primary-active': Color(baseColor).darken(0.1).hex(),
    'primary-disabled': Color(baseColor).alpha(0.5).rgb().string()
  };
}

// 使用
const palette = generateColorPalette('#ef4444');
applyCustomTheme(palette);

这样用户只需要选一个主色，其他状态色自动搞定。不过注意：color 库体积不小（约 5KB gzipped），如果项目对体积敏感，可以自己写个简易的 HSL 调整函数，只处理 lighten/darken。

另外，别在每次渲染时都计算！一定要缓存结果，否则性能会掉。我是把 palette 存进 localStorage，下次直接读，只有主色变了才重新算。

还有这些细节你可能没想到

比如字体切换？其实也可以塞进主题系统：

:root {
  --font-family: 'Inter', sans-serif;
}
[data-theme="compact"] {
  --font-family: 'Helvetica', sans-serif;
  --line-height: 1.4;
}

再比如暗色模式下图片太刺眼？可以给 img 加个 CSS filter：

“css
[data-theme="dark"] img:not(.ignore-dark-mode) {
filter: brightness(0.9) contrast(1.1);
}
`>

当然，这些属于业务定制，不一定每个项目都需要。但架构上留个口子，后面加起来就方便。

还有一点：测试！别以为切换完看着没问题就完事了。一定要检查：

• 表单控件（input、select）在不同主题下的可读性
• 弹窗、tooltip 这类 portal 元素是否继承了正确主题（因为它们可能挂在 body 下，而 body 的 class 可能没更新）
• iOS Safari 下深色模式是否会自动反转颜色（有时会和你的主题冲突）

最后说两句

这套方案不是银弹，但胜在简单、可控、调试方便。我见过有人用 CSS-in-JS 做主题，也有人用 postcss 插件编译多份 CSS，但对大多数中后台项目来说，CSS variables + localStorage 足够了。

目前我在新项目里还会加上一个主题配置面板，拖个滑块就能调色，实时预览，产品经理看了直呼内行（笑）。这部分代码有点长，下次单独写一篇。

以上是我踩坑后的总结，希望对你有帮助。这个技术的拓展用法还有很多，比如结合 design token、对接 Figma 插件自动同步设计稿变量，后续会继续分享这类博客。有更优的实现方式欢迎评论区交流。