Tailwind CSS on kenji.blog

Hugo主题自定义：导入Tailwind CSS的方法

Sun, 13 Sep 2026 03:00:00 +0900

前言：静态网站生成器Hugo与Tailwind CSS的强大协同效应

在现代Web前端开发中，兼顾性能与开发体验（DX：Developer Experience）是所有项目中最重要的课题之一。在静态网站生成器（SSG）中拥有世界最快级别构建速度的Hugo，与引入了效用优先（Utility-First）这一创新范式的Tailwind CSS相结合，可以说是对这个课题的终极解答之一。

Hugo使用Go语言编写，即使是数千页的网站，也能在短短几秒或毫秒级的时间内完成构建，拥有惊人的性能。另一方面，Tailwind CSS通过将预先定义好的无数效用类（如flex, text-center, mt-4等）直接写在HTML中，消除了在CSS文件和HTML文件之间来回切换的上下文切换，加速了设计的迭代。

本文将从架构基础到数学层面性能优化的视角，彻底且详细地讲解如何在Hugo主题中导入Tailwind CSS，以及进一步构建使用PostCSS的高级资产管道（Hugo Pipes）的步骤。

1. 效用优先CSS与组件化的演进

在进入Tailwind CSS的导入步骤之前，深入理解为什么我们应该使用Tailwind CSS，以及其背后的CSS设计思想的历史和演进，是非常有益的。

传统CSS设计（BEM或OOCSS）的局限性

在过去的Web开发中，赋予语义化的类名被认为是最佳实践。例如，在创建一个卡片组件时，HTML和CSS通常像这样分离：

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">标题</h2>
 <p class="card__description">说明文本将放在这里。</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* 之后会有更详细的样式 */

这种基于BEM（Block Element Modifier）的设计在项目规模较小的时候还能起作用，但往往会引发以下问题：

命名枯竭与疲劳：每次制作类似的组件时，都必须想出新的类名（例如：card-news, card-featured等）。
CSS体积膨胀：每次添加新功能，CSS的代码行数就会不断增加，而且一旦写好的CSS往往因为害怕“不知道在哪里被使用了”而不敢删除，导致死代码（Dead Code）不断积累。
上下文切换：因为HTML的结构和CSS的样式是在不同的文件中管理的，所以在编辑器中切换标签的次数会呈指数级增长。

Tailwind CSS带来的范式转变

Tailwind CSS通过“效用类的组合”这种方法来解决这些问题。上述的卡片组件如果使用Tailwind CSS，会变成如下形式：

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">标题</h2>
 <p class="mt-2 text-gray-600">说明文本将放在这里。</p>
 </div>
</div>

由于类名本身就代表了样式的具体值（如p-6代表padding: 1.5rem;等），只需看HTML就能预测出最终的渲染结果。此外，通过Tailwind的JIT（Just-In-Time）编译器，只有实际使用到的类才会被提取到生产环境的CSS文件中，因此CSS的文件大小会被极限压缩。

2. Hugo Pipes与PostCSS的架构

为了将Tailwind CSS集成到Hugo中，必须了解名为Hugo Pipes的资产处理管道。Hugo Pipes是一项强大的功能，它能够在Hugo内部完成诸如Sass/SCSS编译、JavaScript打包和压缩，以及这次我们要使用的PostCSS的执行等所有关于资产的处理。

PostCSS是一个使用JavaScript插件来转换CSS的工具。Tailwind CSS本身实际上也是作为PostCSS的一个插件来运行的。

PostCSS的AST（抽象语法树）转换机制

了解PostCSS是如何处理CSS的，对于进行故障排查非常有帮助。下面的Mermaid图展示了PostCSS读取CSS文件，通过插件进行转换，直到输出最终CSS的管道流程。

flowchart TD
A["原生CSS (styles.css)"] -->|Parser| B["AST (抽象语法树)"]
B --> C["插件 1: Tailwind CSS"]
C --> D["插件 2: Autoprefixer"]
D --> E["插件 N: cssnano"]
E -->|Stringifier| F["编译并优化后的CSS"]

Parser（解析器）：解析输入的原始CSS字符串，将其转换为程序可以操作的数据结构，即AST（抽象语法树）。
Plugins（插件群）：
- Tailwind CSS：扫描模板文件（HTML或Markdown），将在其中使用的效用类作为节点添加到AST上。同时，它还会展开@tailwind指令。
- Autoprefixer：参考Can I Use的数据库，根据需要将浏览器引擎前缀（如-webkit-, -moz-等）添加到AST的属性中。
Stringifier（字符串化器）：将转换完成的AST再次转换为浏览器可以解析的CSS字符串并输出。

3. 环境搭建与前提条件

那么，让我们进入实际的导入步骤。首先确认是否已安装所需的软件。

必备要求

Hugo Extended Version：不是普通的Hugo，而是必须包含Sass/SCSS处理功能以及原生支持PostCSS集成功能的Extended版。在终端中执行以下命令，确认版本信息中包含extended字符串。
1 2 3

hugo version # 预期的输出示例: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js与npm： Tailwind CSS和PostCSS等依赖包需要在Node.js上运行。请确认已安装Node.js（推荐LTS版）。
1 2

node -v npm -v

安装npm包

在项目的根目录（即Hugo的配置文件hugo.toml所在的层级）初始化npm，并安装所需的包。

1
2
3
4
5


# 生成package.json
npm init -y

# 安装Tailwind CSS, PostCSS, Autoprefixer作为开发依赖
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] 如果没有安装postcss-cli，当Hugo内部调用PostCSS时可能会发生错误。因为Hugo Pipes内部使用postcss-cli，所以请务必安装它。

4. 构建配置文件（PostCSS & Tailwind CSS）

包安装完成后，创建两个控制项目行为的重要配置文件。请将它们放在项目根目录下。

创建 tailwind.config.js

在终端中执行以下命令，将会生成默认的配置文件。

1

npx tailwindcss init

使用编辑器打开生成的 tailwind.config.js，设置 content 属性。这里非常重要。Tailwind会解析这里指定路径的文件，并提取其中使用的类。请根据Hugo的项目结构，准确地指定布局文件和内容文件。

 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


/** @type {import('tailwindcss').Config} */
module.exports = {
 // 根据Hugo的目录结构指定扫描目标
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // 如果使用了主题，也必须包含主题的目录
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // 在这里进行自定义颜色和字体的扩展
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // 根据需要添加官方插件（例如：Typography插件）
 // require('@tailwindcss/typography'),
 ],
}

创建 postcss.config.js

接下来，在项目根目录创建 postcss.config.js，用来定义PostCSS执行哪些插件以及执行的顺序。

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

通过这个配置，当Hugo调用PostCSS时，会首先进行Tailwind CSS的处理，然后再由Autoprefixer进行添加浏览器前缀的处理。

5. 在Hugo中构建CSS资产管道

配置完成后，终于可以将Tailwind CSS集成到Hugo主题端了。

5-1. 创建作为入口点的CSS文件

在 assets/css/ 目录（如果不存在请创建它）中，创建一个作为入口点的CSS文件。在这里我们命名为 main.css。

文件路径: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* 导入Tailwind的基础样式（如重置CSS等） */
@tailwind base;

/* 导入组件类 */
@tailwind components;

/* 导入效用类 */
@tailwind utilities;

/* 如果需要自定义CSS，可以写在这里，
 但建议尽可能在tailwind.config.js的extend中进行处理 */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. 编辑布局文件（head.html）

接下来，在Hugo的模板中读取上述的CSS文件，并编写使用PostCSS处理的管道。通常需要编辑定义了 <head> 标签内的局部模板（例如：layouts/partials/head.html）。

文件路径: layouts/partials/head.html

 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


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- 获取 assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- 定义PostCSS选项 -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- 面向生产环境（Production）的资产优化管道 -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify（压缩） -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint（用于缓存破坏的哈希计算） -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. 输出带有SRI（子资源完整性）的标签 -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- 在开发环境（Development）中不压缩，直接输出（优先考虑构建速度） -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

管道说明与Mermaid图解

下面通过图解说明上述的Go模板代码是如何处理CSS文件的一系列管道流程。

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Hugo内存空间"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT 处理"]
C --> D{"hugo.IsProduction ?"}
D -- "Yes (生产环境)" --> E["minify (删除空格与换行)"]
E --> F["fingerprint (计算哈希)"]
F --> G["public/css/main.[hash].css (带SRI)"]
D -- "No (开发环境)" --> H["public/css/main.css"]

resources.Get：在assets目录中查找指定的文件，并将其作为内存中的资源对象加载。
resources.PostCSS：参考项目根目录的postcss.config.js，将Tailwind CSS和Autoprefixer的处理应用到CSS源代码中。在开发环境（hugo server）下，JIT模式会启动，在文件变更时能高速生成所需的类。
minify：在生产环境构建时（例如hugo --environment production），删除不需要的空格和注释，最小化文件大小。
fingerprint：根据文件内容计算SHA哈希值，并附加在文件名上（例如：main.ab12cd...css）。这使得可以在利用浏览器强大的缓存机制的同时，在CSS更新时可靠地加载新文件，实现了“缓存破坏”。
integrity：利用Fingerprint计算出的哈希值，输出SRI属性以防止来自CDN等的篡改。

6. CSS优化中的数学性能分析

引入Tailwind CSS最大的优点之一，就是将分发的CSS文件大小减小到极致。让我们使用数学模型来定量分析这会对Web性能（特别是首次内容绘制：FCP）产生怎样的影响。

CSS文件大小缩减模型

在传统的CSS框架（如Bootstrap等）中，因为包括未使用的样式在内的全部代码都会被加载，所以文件大小 $S_{original}$ 往往会很大（约150KB～200KB）。假设Tailwind CSS的JIT编译器清除了（Purge）未使用的类后的大小为 $S_{purged}$，使用缩减率 $R_{purge}$ 可以表示为：

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

在典型的项目中，$R_{purge}$ 会接近 $0.9$（减少90%），$S_{purged}$ 将缩小到仅有10KB～20KB左右。

此外，在分发时服务器端会进行Brotli或Gzip压缩。如果压缩率为 $R_{compress}$（通常在0.7～0.8左右），在网络中流动的最终负载大小 $S_{final}$ 将通过以下公式计算：

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

关键渲染路径与网络延迟

浏览器在屏幕上绘制出第一个内容的时间（FCP），可以近似为HTML下载时间、CSS下载时间与渲染时间之和。

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

这里：

$RTT$ : 往返时间（与服务器之间的往返通信延迟时间）
$BW$ : 网络带宽（Bandwidth）

在移动网络等 $BW$ 较窄、$RTT$ 较大（延迟大）的环境中，Tailwind CSS将 $S_{final}$ 削减到几千字节级别的方法，能将 $\frac{S_{final}}{BW}$ 这一项极度趋近于零，成为在Google PageSpeed Insights等工具中获得惊人高分的驱动力。

7. 启动开发服务器并验证热重载

所有配置完成后，启动Hugo的开发服务器，确认Tailwind CSS是否正常工作。

1

hugo server -D

在浏览器中访问 http://localhost:1313/，确认网站已显示。尝试打开Markdown内容文件或Hugo的模板（layouts/ 下的文件），并添加一些类。

1
2
3
4
5


<!-- 用于测试的Tailwind类应用示例 -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">请确认热重载是否能够瞬间生效。</p>
</div>

保存文件的瞬间，Hugo强大的文件监听器和Tailwind的JIT编译器将协同工作，让你体验到在几毫秒内重新构建CSS并自动刷新浏览器（热重载）的快感。

故障排查：样式未生效的情况

如果更改未生效，请检查以下几点：

tailwind.config.js 中的 content 路径设置 如果扫描目标的文件路径错误，Tailwind将无法检测到该文件中使用的类，也不会将其输出到CSS中。特别是在使用主题的情况下，请确认是否遗漏了主题目录的路径。
PostCSS错误 如果终端中Hugo服务器的日志输出了类似 Error: failed to transform resource: PostCSS not found 的错误，可能是 npm install 未正确执行，或者缺少 postcss-cli。
清除Hugo缓存 在极少数情况下，因为Hugo的缓存问题可能会残留旧的CSS。请尝试停止服务器，然后使用 hugo server --ignoreCache 启动，或者删除OS的临时目录（如 /tmp/hugo_cache/ 等）。

8. 面向生产环境的构建与进一步进阶

在将网站部署到生产服务器（如Netlify, Vercel, GitHub Pages, Cloudflare Pages等）时，需要设置环境变量来运行生产用的优化管道。

1
2


# 生产构建命令示例
NODE_ENV=production hugo --minify --environment production

加上 --environment production 标志后，head.html 中的 {{ if hugo.IsProduction }} 代码块会被执行，从而进行CSS的Minify压缩和添加Fingerprint哈希。

使用Typography插件为Markdown添加样式

在像Hugo这样的博客或文档网站中，我们无法直接向由Markdown生成的纯HTML元素（如 <h1>, <p>, <ul> 等）添加类名。在这种情况下，非常有用的是Tailwind官方的 Typography插件。

安装插件

1

npm install -D @tailwindcss/typography

添加到 tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

在模板中应用只要在输出文章正文的容器元素上添加 prose 类（以及你喜欢的颜色或尺寸的变体），就能应用优美的默认样式。
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

通过这种方式，就完全不需要手写复杂的CSS选择器（如 .article-content h2 { ... }）了，从而完美地保持了组件的模块化。

9. 总结：高可维护性前端生态系统的完成

辛苦了。至此，一个兼备Hugo超高速静态站点生成引擎、Tailwind CSS现代样式功能以及PostCSS可扩展性的完美的Web开发资产管道就完成了。

这种架构的优点在于**“配置只需进行一次即可”**。一旦搭建好管道，开发者就无需打开CSS文件，只需直观地将效用类写在HTML或Markdown模板中，便能以惊人的速度搭建出复杂的UI。

此外，由于输出的CSS大小总是被最小化的，这直接提升了Core Web Vitals的分数，从SEO的角度来看也非常有利。

Hugo与Tailwind CSS的组合，无论是对于个人的技术博客还是大型的企业网站，在所有项目中都将继续是“最佳选择”之一。请务必活用这条强大的工具链，享受舒适的Web开发生活吧！

博客深色模式支持中的CSS设计要点

Sat, 12 Sep 2026 12:00:00 +0900

现代Web开发中，深色模式（Dark Mode）的支持已经从单纯的“锦上添花的特性（Nice to have）”转变为提升用户体验（UX）的“必备要求（Must have）”。特别是像博客和文档网站这样需要长时间阅读文本的媒体，它能够减轻用户的眼睛疲劳，并降低设备的电池消耗，因此支持深色模式的重要性可以说是极高的。

本文将从前端工程师的视角，极其深入地剖析博客在适配深色模式时不可避免的技术挑战和高可维护性CSS设计要点。涵盖的内容包括：利用CSS Custom Properties（CSS变量）、防止FOUC（Flash of Unstyled Content）的高级JavaScript控制与SSR结合、确保无障碍访问（WCAG 2.1 AAA）的色彩设计（RGB、HSL以及最新的OKLCH），还有使用Tailwind CSS的实用代码示例，网罗深色模式实现的方方面面。

1. 基于CSS Custom Properties（CSS变量）的主题设计基础

在实现深色模式时，目前最标准且强大的方法是利用 CSS Custom Properties（CSS变量）。与Sass等CSS预处理器的变量（$color）在编译时静态解析不同，CSS变量是在浏览器的运行时动态解析和覆盖的。由此，只需通过JavaScript切换类名，即可瞬间改变整个页面的色调。

1.1 基本色彩主题的定义

首先，使用 :root 伪类定义浅色模式（默认）的调色板。然后，当赋予 [data-theme='dark'] 等属性（或 .dark 类）时，对这些变量进行覆盖，这是最经典的设计模式。

 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


/* 浅色模式（默认）的变量定义 */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* 深色模式时的变量覆盖 */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* 实际应用 */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

如此这般，通过将布局或排版的指定与颜色（主题）的指定完全分离，CSS的可维护性将会实现飞跃性的提升。

1.2 灵活运用 @media (prefers-color-scheme: dark)

如果操作系统级别设置了深色模式，从用户首次访问网站开始自动应用深色主题，从UX的角度来看是更理想的。实现这一点的正是 @media (prefers-color-scheme: dark) 这个媒体查询。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* 当操作系统的环境设置为深色模式时的回退方案 */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

在这种写法中，除非用户明确选择了浅色模式（data-theme='light'），否则会尊重操作系统的深色模式设置来覆盖变量。

2. 理解色彩空间与无障碍访问（WCAG 2.1 AAA）

在深色模式的色彩设计中，仅仅“把背景变黑，文字变白”是不够的。如果对比度过强，会引起光晕现象反而难以阅读；而如果对比度过低，又会损害可视性。Web Content Accessibility Guidelines (WCAG) 对确保可视性的对比度进行了严格的定义。

2.1 WCAG 对比度计算公式

WCAG 中的对比度（Contrast Ratio） $CR$ 使用背景色和前景色（文本色）的相对亮度（Relative Luminance）定义如下：

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

这里，$L_{lighter}$ 是较亮颜色的相对亮度，$L_{darker}$ 是较暗颜色的相对亮度（值的范围是 0.0 到 1.0）。为了达到 WCAG 2.1 的 AAA 级别，常规文本需要 7:1 以上，大文本需要 4.5:1 以上 的对比度。

相对亮度 $L$ 可由 sRGB 色彩空间的 RGB 值通过以下复杂的公式计算得出：

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

各分量（$R, G, B$）是使用原有的 8 位值（$R_{sRGB}$）除以 255 后的归一化值，为解除伽马校正进行如下转换：

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

手动进行这样的计算很困难，但通过利用色彩设计工具，可以机械地挑选出满足对比度 7:1 ($CR \ge 7.0$) 的颜色。

2.2 HSL vs RGB vs OKLCH

在创建调色板时，过去 RGB 或 HSL 是主流。然而，从“感知均匀性”的角度来看，它们有着巨大的缺陷。

RGB: 机械的光学三原色，人类难以直观地进行“调亮”或“调暗”之类的调整。
HSL: 使用色相 (Hue)、饱和度 (Saturation) 和亮度 (Lightness)，但 HSL 的“亮度 (L)”与人类眼睛感知的亮度并不一致。例如，在 HSL 中亮度同为 50% 的纯黄色和纯蓝色，在数值上亮度相同，但在人眼看来黄色却亮得多。
OKLCH: 近年在 CSS Color Module Level 4 中引入的最新色彩空间。由 Lightness（感知明度）、Chroma（饱和度）、Hue（色相）组成，完全符合人类的视觉特性（感知均匀）。

通过使用 OKLCH，即使改变色相（Hue）也能保持相同的感知明度（Lightness），这使得为深色模式生成调色板变得极具可预测性且安全。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* 使用 OKLCH 定义 CSS 变量的示例 */
:root {
 /* 浅色模式的基础明度较高，饱和度较低 */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* 在深色模式中只需反转明度，即可轻松保持感知对比度 */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* 针对深色模式稍作提亮以确保可视性 */
}

这样通过采用 OKLCH，就能非常简单地构建起在多个主题间保证一致对比度（WCAG AAA 水平）的逻辑。

3. 防止FOUC（Flash of Unstyled Content）与SSR水合作用

在支持深色模式时最令开发者头疼的，就是被称为 FOUC (Flash of Unstyled Content) 的画面闪烁问题。

3.1 客户端 JS 切换主题的陷阱

在 React 或 Vue 等 SPA（或 SSG 生成的静态网站）中，将用户的设置保存在 localStorage，然后用 JavaScript 读取并切换主题是常见的做法。然而，如果在 React 的 useEffect 等中执行此操作，就会发生以下问题：

浏览器渲染浅色模式的 HTML/CSS。
JS 包被加载并执行。
从 localStorage 读取 dark 设置。
HTML 被赋予 dark 类，画面突然变暗（闪烁）。

为了彻底防止 FOUC 并避免水合错误（Hydration Error），最佳实践是 将用户的主题设置保存在 document.cookie 中，并在服务器端渲染（SSR）阶段返回赋予了合适类名的 HTML。

以下的时序图展示了利用 Cookie 进行主题初始化的理想流程：

sequenceDiagram
participant User as "用户"
participant Browser as "浏览器 操作系统"
participant Server as "服务器 SSR"
participant DOM as "客户端 DOM"
User->>Browser: "请求页面"
Browser->>Server: "携带 Cookie (theme=dark) 的 GET 请求"
Server-->>Browser: "返回包含 <html data-theme='dark'> 的 HTML"
Browser->>DOM: "渲染初始 HTML (无 FOUC)"
DOM->>DOM: "执行水合脚本"
alt "无 Cookie (首次访问)"
DOM->>Browser: "检查操作系统 prefers-color-scheme"
Browser-->>DOM: "matchMedia 结果 (例如 dark)"
DOM->>DOM: "通过内联阻塞脚本设置 data-theme='dark'"
end

对于仅支持 SSG（静态网站生成）且无法进行 SSR 的博客（例如 Hugo、Gatsby 或 Astro 的静态导出等），必须在 <head> 标签内部放置会阻塞渲染的内联 JavaScript，并在 DOM 渲染前一刻赋予相应类名，这是必不可少的方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 放置在 <head> 内部的最后 -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

这段简短的脚本会阻塞浏览器的渲染并立即执行，因此在画面渲染时就已经设置好了 data-theme 属性，能够彻底防止画面的闪烁（FOUC）。

4. Tailwind CSS 与原生 SCSS/CSS 的实现方法

将深色模式引入实际项目时，需要了解各个工具的实现方法。

4.1 Tailwind CSS 中的深色模式

Tailwind CSS 默认提供了 dark: 变体（variant），可以非常简单地实现深色模式。在配置文件（tailwind.config.js）中设置 darkMode 属性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (依赖操作系统设置) 或 'class' (可手动切换)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* 利用 CSS 变量扩展 Tailwind 的调色板 */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

在 HTML 方面只需像下面这样添加类名即可。

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

然而，对所有元素都写上 dark:bg-xxx 也会成为组件变得臃肿的原因。在大型博客或应用程序中，推荐采用以 CSS 变量为基础，从 Tailwind 引用这些 CSS 变量的混合设计（语义化颜色设计）。

以下是展示 CSS 变量继承和应用层级的类图：

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "应用工具类"

4.2 使用原生 SCSS/CSS 实现（活用 Mixin）

在不使用 Tailwind 而独立编写 SCSS 的项目中，可以利用 @mixin 将深色模式的样式封装起来。

 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


/* SCSS Mixin 的定义 */
@mixin dark-mode {
 /* 支持 [data-theme='dark'] 属性，或操作系统设置 */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* 使用示例 */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

这种方法虽然直观，但编译后的 CSS 文件体积容易膨胀（媒体查询会被复制到各个选择器中），因此目前的趋势仍然是过渡到以 CSS 变量（Custom Properties）为核心的设计。

5. 图片（Image）与 SVG 的深色模式优化

即使文本和背景的色彩设计已经完成，如果作为内容放置的图片或图标（SVG）仍然保持浅色模式的状态，在深色模式下就会显得非常刺眼且格格不入。对它们进行优化也是必不可少的。

5.1 降低图片亮度的 CSS 滤镜

如果将照片等位图图像在深色模式下原样显示，有时会过于刺眼。通过使用 CSS 的 filter 属性，稍微降低图像的亮度（brightness）并增加对比度（contrast），就能使其自然地融入深色主题的 UI 中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* 降低亮度，稍微提高对比度 */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* 悬停时恢复原有的亮度（为了用户想要查看细节的情况） */
 filter: brightness(1) contrast(1);
}

5.2 使用 `<picture>` 标签切换图片

像 Logo 或说明用的图解（如背景固定为白色的 JPEG）等，仅靠滤镜处理是无法解决的。在这种情况下，正确的做法是结合 HTML 的 <picture> 元素和媒体查询，为深色模式提供另一份图片文件。

1
2
3
4
5
6


<picture>
 <!-- 向系统设置为深色模式的用户显示这张图片 -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- 默认（浅色模式） -->
 <img src="/img/logo-light.png" alt="网站 Logo">
</picture>

※需要注意的是，这种方法不会与 localStorage 等手动切换功能联动（仅依赖于操作系统设置）。如果实现了手动切换，则需要使用 JS 动态修改图片的 src，或者通过 CSS 类切换 display: none。

5.3 SVG 图标的 `currentColor` 适配

对于图标等处使用的内联 SVG，将其填充颜色与父元素的文本颜色联动是最高明的做法。只需将 SVG 的 fill 或 stroke 属性指定为 currentColor 即可。

1
2
3
4


<!-- CSS 的 color 属性的值（例如 var(--text-primary)）将自动被应用 -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

由此一来，当切换到深色模式，父元素的文字颜色变成白色系时，SVG 图标也会自动变为白色系。

6. 总结：迈向可持续的深色模式设计

在博客或 Web 应用程序中，要实现高质量的深色模式，涵盖以下要点的 CSS 设计是不可或缺的：

活用 CSS Custom Properties（CSS变量）: 避免硬编码颜色指定，将其抽象为语义化的变量名（例: --bg-primary）。
采用 OKLCH 色彩空间: 在感知均匀的色彩空间中进行符合逻辑的设计，以满足 WCAG 2.1 AAA 标准中高无障碍访问的对比度（7:1 以上）。
彻底做好 FOUC 防御对策: 结合 SSR 和 Cookie，或使用 <head> 内的阻塞式内联脚本，彻底消除初次加载时的画面闪烁。
媒体与静态资源的优化: 充分运用 filter: brightness()、currentColor 以及 <picture> 标签，使文本以外的元素也能与深色主题相得益彰。

超越了单纯的“颜色反转”，正是这些细致入微的考量，才能被称为是一个能够长期受用户喜爱、提供不伤眼且卓越阅读体验（Reading Experience）的现代博客的条件。准备引入深色模式的开发者们，请务必参考本文的设计模式。