结论:必须用 localStorage + class 切换实现暗黑模式,而非仅依赖 @media (prefers-color-scheme: dark);主题样式需统一收口至根 class,CSS 变量按亮色默认、暗色覆盖原则组织,并兼顾打印、OLED 显示与 ATS 兼容性。

直接给结论:别用 @media (prefers-color-scheme: dark) 单独撑全场,它只反映系统设置,不反映用户此刻真实意图。简历页上一段浅灰 代码块在纯黑背景里直接“消失”,这种体验不是暗黑模式,是阅读灾难。
为什么 localStorage + class 切换比纯媒体查询更可靠
用户点一次 ☀️/? 按钮,你就得记住他这次选择,并且下次打开立刻生效——localStorage 是唯一能跨页面保留这个意图的机制。媒体查询只在页面加载时读一次系统偏好,之后就“失联”了。
-
localStorage.setItem('theme', 'dark')必须在点击切换时同步执行,不能只改 class - 页面初始化时优先读
localStorage.getItem('theme'),没值才 fallback 到matchMedia('(prefers-color-scheme: dark)') - 所有主题样式必须收口到一个根 class 上,比如
,而不是散落在十几个@media块里 - 避免用
document.body.classList.toggle()这类无状态操作——它不感知 localStorage,关掉页面再开,主题就“回档”
CSS变量怎么组织才不翻车
把颜色、阴影、边框这些可变项全扔进 :root,但别只写一套。亮色模式是默认值,暗色模式靠 class 覆盖,而不是靠媒体查询重写。
- 定义统一前缀,比如
--bg-primary、--text-secondary,别用--dark-bg这种语义耦合的命名 - 暗色模式下,
.theme-dark :root里重设变量值,而不是写新变量名 - 表单控件(
、)要单独处理:OLED 屏幕下纯黑背景+深灰文字对比度不够,建议用#121212作背景,#e0e0e0作文字 - 慎用
filter: invert(1) hue-rotate(180deg)这类“一键暗黑”技巧——图片、SVG、icon font 全会翻转错乱,且无法控制粒度
简历特有的暗黑适配陷阱
简历不是普通网页,它要打印、要 ATS 解析、要在手机 Safari 里正常缩放。深色模式一加,这些问题会立刻放大。
- 打印时必须强制白底黑字:
@media print { html.theme-dark { background: #fff !important; color: #000 !important; } } - 代码块
在暗色下极易糊成一片,固定加background: #1e1e1e; color: #d4d4d4;,别依赖变量 - 技能标签用
+background实现时,暗色模式下别用纯黑边框(#000),换成#333,否则和背景融成一块 - 本地双击打开 index.html 正常,上传 GitHub Pages 后变白屏?大概率是 CSS 里用了相对路径引用字体或图标,而暗色模式 JS 初始化逻辑被路径错误阻断
最易被忽略的一点:暗黑模式不是“加黑底+浅字”就完事。它本质是一套视觉权重重分配——标题要更跳,时间线要更清晰,代码块要可读,打印时还得自动退回到高对比度白底。所有这些,都得靠 class 控制流 + 变量 + 打印媒体查询三者咬合,缺一不可。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











