本文详解如何利用 localstorage 在纯静态网站中实现暗黑模式状态的跨会话、跨页面持久化保存，确保用户刷新、跳转或重新访问时自动恢复上次选择的主题，无需后端支持。
本文详解如何利用 localstorage 在纯静态网站中实现暗黑模式状态的跨会话、跨页面持久化保存，确保用户刷新、跳转或重新访问时自动恢复上次选择的主题，无需后端支持。
在静态 HTML 网站中实现“记住上次主题”的能力，核心在于将用户交互产生的状态（如是否启用 .dark-mode）从易失的 DOM 操作，升级为持久化的客户端存储。localStorage 是最轻量、兼容性最佳（IE8+ 及所有现代浏览器均支持）、零服务端依赖的解决方案——它恰好匹配静态站点的技术边界。
✅ 正确初始化：读取并应用历史偏好
页面加载时，必须先读取 localStorage，再更新 DOM，而非等待用户点击。否则首次访问永远是亮色模式，违背“记忆”初衷。关键要点：
- 使用
localStorage.getItem('dark-mode')获取字符串值（注意：localStorage只存字符串）； - 严格比对
'true'（而非真值判断），避免JSON.parse()前错误处理导致异常； - 若值不存在（首次访问），可结合
prefers-color-scheme提供智能默认（见进阶建议）。
const html = document.querySelector('html');
const button = document.querySelector('.contrast-toggle');
// 初始化：读取并应用保存的主题
const savedTheme = localStorage.getItem('dark-mode');
if (savedTheme === 'true') {
html.classList.add('dark-mode');
}
// 切换逻辑：同步 DOM 与存储
button.addEventListener('click', (e) => {
e.preventDefault();
html.classList.toggle('dark-mode');
// 安全写入：仅存布尔对应的字符串
localStorage.setItem('dark-mode', html.classList.contains('dark-mode'));
});
⚠️ 注意事项与健壮性增强
-
避免重复触发与竞态：当前页修改
localStorage不会触发自身的storage事件，因此无需防抖；但若网站含多标签页，建议补充window.addEventListener('storage', ...)监听其他标签页变更（本例未展开，属进阶需求）。 -
CSS 层级安全：推荐使用
html.dark-mode而非body.dark-mode，确保样式优先级稳定，尤其当 CSS 框架（如 Tailwind）存在全局类冲突时。 -
可访问性基础：按钮应使用
<button></button>而非<a></a>（语义正确、天然支持键盘操作），并添加aria-pressed属性动态同步状态（示例略，强烈建议补充）。 -
兜底策略（推荐）：首次无存储时，可降级读取系统偏好：
const systemPrefersDark = window.matchMedia?.('(prefers-color-scheme: dark)').matches; if (savedTheme === null) { if (systemPrefersDark) html.classList.add('dark-mode'); }
? 进阶提示：超越 localStorage 的边界
-
localStorage数据随浏览器缓存清除而丢失，且无法跨设备同步。如需更高可靠性，需引入后端 API + 用户身份体系（如 JWT 认证后存入数据库），但这已超出静态网站范畴。 - 对于 SEO 和首屏体验，服务端渲染（SSR）站点应在 HTML 输出阶段即注入
data-theme="dark"，避免 JS 加载前的“闪屏”。
至此，你已拥有一套简洁、可靠、符合现代 Web 最佳实践的暗黑模式持久化方案——无需框架、不依赖网络、开箱即用。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
