Tailwind CSS 暗色模式从零搭建

Sat, 23 Nov 2024 00:00:00 +0000

暗色模式不只是加个 dark: 前缀那么简单。这篇记录我在 RuiToolAI 里搭建完整暗色模式体系的过程。

为什么暗色模式容易搞乱

暗色模式最常见的问题：

颜色硬编码：text-gray-900 在暗色下看不见
闪烁（FOUC）：页面加载时先显示亮色再切换到暗色
图片/图标不适配：亮色图标在暗色背景上消失
第三方组件不跟随：自己的组件暗色了，Shadcn 组件还是亮色

Tailwind 暗色模式配置

Tailwind 支持两种暗色模式策略：

1
2
3
4
5
6
7
8


// tailwind.config.ts
export default {
 // 方案一：跟随系统（media）
 darkMode: "media",

 // 方案二：手动切换（class）—— 推荐
 darkMode: "class",
};

推荐用 class 方案，因为：

用户可以手动切换，不受系统设置影响
可以持久化到 localStorage
SSR 时可以从 cookie 读取，避免闪烁

CSS 变量 + Tailwind 的组合方案

硬编码颜色是暗色模式的大敌。正确做法是用 CSS 变量定义语义化颜色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


/* src/app/globals.css */
@layer base {
 :root {
 --background: 0 0% 100%;
 --foreground: 222.2 84% 4.9%;
 --card: 0 0% 100%;
 --card-foreground: 222.2 84% 4.9%;
 --primary: 221.2 83.2% 53.3%;
 --primary-foreground: 210 40% 98%;
 --muted: 210 40% 96.1%;
 --muted-foreground: 215.4 16.3% 46.9%;
 --border: 214.3 31.8% 91.4%;
 --radius: 0.5rem;
 }

 .dark {
 --background: 222.2 84% 4.9%;
 --foreground: 210 40% 98%;
 --card: 222.2 84% 4.9%;
 --card-foreground: 210 40% 98%;
 --primary: 217.2 91.2% 59.8%;
 --primary-foreground: 222.2 47.4% 11.2%;
 --muted: 217.2 32.6% 17.5%;
 --muted-foreground: 215 20.2% 65.1%;
 --border: 217.2 32.6% 17.5%;
 }
}

然后在 tailwind.config.ts 里把这些变量映射成 Tailwind 颜色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
 darkMode: "class",
 theme: {
 extend: {
 colors: {
 background: "hsl(var(--background))",
 foreground: "hsl(var(--foreground))",
 card: {
 DEFAULT: "hsl(var(--card))",
 foreground: "hsl(var(--card-foreground))",
 },
 primary: {
 DEFAULT: "hsl(var(--primary))",
 foreground: "hsl(var(--primary-foreground))",
 },
 muted: {
 DEFAULT: "hsl(var(--muted))",
 foreground: "hsl(var(--muted-foreground))",
 },
 border: "hsl(var(--border))",
 },
 },
 },
};

这样写组件时只需要用语义化类名，暗色模式自动切换：

1
2
3
4


// 不需要写 dark: 前缀
<div className="bg-background text-foreground">
 <p className="text-muted-foreground">副标题</p>
</div>

主题切换实现

避免闪烁的关键

闪烁（FOUC）发生在：服务端渲染了亮色 HTML，客户端 JS 加载后才切换到暗色，用户看到一闪。

解决方案：在 <head> 里内联一段脚本，在页面渲染前就设置好 class：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// src/app/layout.tsx
export default function RootLayout({
 children,
}: {
 children: React.ReactNode;
}) {
 return (
 <html lang="zh" suppressHydrationWarning>
 <head>
 {/* 内联脚本，在 HTML 解析时立即执行，避免闪烁 */}
 <script
 dangerouslySetInnerHTML={{
 __html: `
 (function() {
 try {
 var theme = localStorage.getItem('theme');
 if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
 document.documentElement.classList.add('dark');
 }
 } catch (e) {}
 })();
 `,
 }}
 />
 </head>
 <body>{children}</body>
 </html>
 );
}

suppressHydrationWarning 是必须的，因为服务端和客户端的 class 可能不同。

主题切换组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// src/components/theme-toggle.tsx
"use client";
import { useEffect, useState } from "react";
import { SunIcon, MoonIcon } from "@heroicons/react/24/outline";

export function ThemeToggle() {
 const [isDark, setIsDark] = useState(false);

 useEffect(() => {
 // 初始化时读取当前主题
 setIsDark(document.documentElement.classList.contains("dark"));
 }, []);

 function toggle() {
 const next = !isDark;
 setIsDark(next);
 if (next) {
 document.documentElement.classList.add("dark");
 localStorage.setItem("theme", "dark");
 } else {
 document.documentElement.classList.remove("dark");
 localStorage.setItem("theme", "light");
 }
 }

 return (
 <button
 onClick={toggle}
 className="rounded-md p-2 hover:bg-muted transition-colors"
 aria-label={isDark ? "切换到亮色模式" : "切换到暗色模式"}
 >
 {isDark ? (
 <SunIcon className="h-5 w-5" />
 ) : (
 <MoonIcon className="h-5 w-5" />
 )}
 </button>
 );
}

Shadcn UI 的暗色模式集成

Shadcn UI 的组件本身已经支持暗色模式，因为它们内部用的就是 CSS 变量（bg-background、text-foreground 等）。

只要你的 CSS 变量配置正确，Shadcn 组件会自动跟随主题切换。

但有一个坑：Shadcn 的 cn() 工具函数。

1
2
3
4
5
6
7


// src/lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
 return twMerge(clsx(inputs));
}

当你用 dark: 前缀覆盖 Shadcn 组件的默认样式时，twMerge 会正确处理冲突，不会出现样式叠加问题。

常见坑点

坑 1：图片在暗色下太亮

1
2
3
4
5
6


// 给图片加暗色滤镜
<img
 src="/logo.png"
 className="dark:brightness-90 dark:invert"
 alt="Logo"
/>

坑 2：渐变在暗色下不好看

1
2


// 亮色：浅蓝渐变；暗色：深蓝渐变
<div className="bg-gradient-to-r from-blue-50 to-indigo-50 dark:from-blue-950 dark:to-indigo-950">

坑 3：边框在暗色下消失

1
2
3
4


// 用语义化 border 颜色
<div className="border border-border">
 {/* border 颜色会随主题切换 */}
</div>

坑 4：第三方库的弹窗/Portal 不跟随主题

有些第三方库把弹窗挂载到 document.body，不在 .dark 类的作用范围内。

解决方案：把 .dark 类加到 <html> 而不是 <body>，这样所有子元素都能继承。

实战：给 Testimonials 组件加暗色支持

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


// src/components/landing/testimonials.tsx
export function Testimonials() {
 return (
 <section className="py-16 bg-background">
 <div className="max-w-7xl mx-auto px-4">
 <h2 className="text-3xl font-bold text-center text-foreground mb-12">
 用户评价
 </h2>

 {/* 滚动容器 */}
 <div className="relative overflow-hidden">
 {/* 左侧渐变遮罩 */}
 <div className="absolute left-0 top-0 bottom-0 w-24 z-10 bg-gradient-to-r from-background to-transparent" />

 {/* 右侧渐变遮罩 */}
 <div className="absolute right-0 top-0 bottom-0 w-24 z-10 bg-gradient-to-l from-background to-transparent" />

 <div className="flex gap-6 animate-marquee hover:[animation-play-state:paused]">
 {testimonials.map((item, i) => (
 <div
 key={i}
 className="flex-shrink-0 w-80 p-6 rounded-xl border border-border bg-card text-card-foreground shadow-sm"
 >
 <p className="text-muted-foreground mb-4">{item.content}</p>
 <div className="flex items-center gap-3">
 <img
 src={item.avatar}
 alt={item.name}
 className="w-10 h-10 rounded-full object-cover"
 />
 <div>
 <p className="font-medium text-foreground">{item.name}</p>
 <p className="text-sm text-muted-foreground">{item.role}</p>
 </div>
 </div>
 </div>
 ))}
 </div>
 </div>
 </div>
 </section>
 );
}

注意渐变遮罩用的是 from-background，这样在暗色模式下遮罩颜色也会自动切换，不会出现白色遮罩盖在暗色背景上的问题。

总结

搭建完整暗色模式体系的关键步骤：

CSS 变量定义语义化颜色：:root 和 .dark 分别定义
Tailwind 映射 CSS 变量：tailwind.config.ts 里配置
内联脚本避免闪烁：在 <head> 里提前设置 class
组件用语义化类名：bg-background、text-foreground，而不是 bg-white、text-gray-900
渐变遮罩用语义化颜色：from-background 而不是 from-white

Shadcn on HanGR的碎碎念