Bootstrap 5.3 深色模式配置指南：从入门到部署
2026-07-09 ·
Bootstrap 5.3 引入的官方色彩模式（深色模式）是近年来最重要的一次更新。本文将手把手教你如何在项目中集成深色模式，包括基础配置、JavaScript API、自定义主题色和实际部署建议。
什么是色彩模式
Bootstrap 5.3 的色彩模式机制基于 CSS 自定义属性和 data-bs-theme 属性实现。与常见的"手动写两套样式"不同，Bootstrap 的深色模式是设计系统级别的原生支持：
- 所有颜色和背景色通过
--bs-* CSS 变量定义
- 深色模式下，这些变量自动切换到暗色值
- 无需重新编译 Sass，在运行时即可切换
- 所有内置组件开箱即用，自动适配
环境要求
色彩模式需要 Bootstrap 5.3.0 及以上版本。可以通过以下方式确认版本：
npm list bootstrap
# 或查看 package.json
"dependencies": {
"bootstrap": "^5.3.3"
}
如果使用 CDN，确保版本号大于等于 5.3.0：
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
基础配置
最简单的深色模式集成方式是在 <html> 标签上添加 data-bs-theme="dark" 属性：
<html lang="zh-CN" data-bs-theme="dark">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>深色模式页面</title>
</head>
<body>
<div class="container py-5">
<h1>深色模式已激活</h1>
<p>所有组件自动适配深色主题</p>
<button class="btn btn-primary">主要按钮</button>
<div class="card mt-3">
<div class="card-body">
卡片内容自动适配深色背景
</div>
</div>
</div>
</body>
</html>
三种模式详解
Bootstrap 5.3 支持三种色彩模式：
1. 浅色模式（Light）
默认模式，无需额外设置。如果需要显式指定：
<html data-bs-theme="light">
2. 深色模式（Dark）
全局开启深色模式：
<html data-bs-theme="dark">
3. 跟随系统（Auto）
不设置 data-bs-theme 属性，或者在 JS 中根据 prefers-color-scheme 媒体查询动态切换：
// 检测系统偏好
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.setAttribute('data-bs-theme', prefersDark ? 'dark' : 'light');
// 监听系统主题变化
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
document.documentElement.setAttribute('data-bs-theme', e.matches ? 'dark' : 'light');
});
主题切换按钮实现
以下是一个完整的主题切换按钮实现，包含本地存储持久化：
<button id="themeToggle" class="btn btn-outline-secondary">
<i class="bi-moon-stars"></i> 切换主题
</button>
<script>
(function() {
// 从 localStorage 读取保存的主题
var saved = localStorage.getItem('bsTheme');
if (saved) {
document.documentElement.setAttribute('data-bs-theme', saved);
}
document.getElementById('themeToggle').addEventListener('click', function() {
var current = document.documentElement.getAttribute('data-bs-theme');
var next = current === 'dark' ? 'light' : 'dark';
document.documentElement.setAttribute('data-bs-theme', next);
localStorage.setItem('bsTheme', next);
});
})();
</script>
自定义深色主题色
Bootstrap 5.3 为深色模式定义了独立的 CSS 变量。通过覆盖这些变量，可以实现完全自定义的深色主题：
[data-bs-theme="dark"] {
--bs-body-bg: #121212;
--bs-body-color: #e0e0e0;
--bs-primary: #bb86fc;
--bs-primary-rgb: 187, 134, 252;
--bs-secondary: #03dac6;
--bs-secondary-rgb: 3, 218, 198;
--bs-success: #4caf50;
--bs-info: #2196f3;
--bs-warning: #ff9800;
--bs-danger: #f44336;
--bs-border-color: #333333;
--bs-link-color: #bb86fc;
--bs-link-hover-color: #ce93d8;
--bs-card-bg: #1e1e1e;
--bs-card-border-color: #333333;
--bs-dropdown-bg: #1e1e1e;
--bs-dropdown-border-color: #333333;
--bs-navbar-bg: #1e1e1e;
}
部分区域深色模式
并非整个页面都必须统一主题，可以在某个容器内独立设置深色模式：
<div data-bs-theme="dark" class="p-4 rounded">
<h3>深色区域</h3>
<p>此区域内的组件使用深色主题</p>
<button class="btn btn-primary">按钮</button>
<div class="card">
<div class="card-body">深色卡片</div>
</div>
</div>
Sass 变量配置
如果使用 Sass 源码编译，可以通过变量自定义深色模式的颜色映射：
// 在导入 Bootstrap 之前定义
$primary: #6f42c1;
$body-bg-dark: #1a1a2e;
$body-color-dark: #e0e0e0;
$primary-dark: #bb86fc;
$secondary-dark: #03dac6;
@import "bootstrap/scss/bootstrap";
常见问题
深色模式下图片太亮怎么办？
可以为深色模式下的图片添加透明度降低亮度的样式：
[data-bs-theme="dark"] img {
opacity: 0.85;
transition: opacity 0.3s;
}
[data-bs-theme="dark"] img:hover {
opacity: 1;
}
深色模式与 Chart.js / ECharts 如何配合？
图表库通常需要手动切换主题。可以通过监听 data-bs-theme 变化来同步更新图表配置：
const observer = new MutationObserver(function() {
var theme = document.documentElement.getAttribute('data-bs-theme');
chart.updateOptions({ theme: theme === 'dark' ? 'dark' : 'light' });
});
observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-bs-theme'] });
总结
Bootstrap 5.3 的色彩模式让深色主题集成变得前所未有的简单。核心要点：
- 使用
data-bs-theme 属性控制主题
- 通过 CSS 变量自定义深色配色
- 结合
localStorage 实现主题偏好持久化
- 利用
prefers-color-scheme 媒体查询跟随系统偏好
更多细节请参考 色彩模式文档。