light-dark() 函数需声明 color-scheme: light dark 才生效，仅作用于颜色属性，不支持非颜色值、变量或嵌套媒体查询，且不响应手动主题切换。
light-dark() 函数在 2026 年已正式进入 CSS Color Module Level 5 规范，并被 Chrome 124+、Firefox 125+、Safari 17.4+ 原生支持——但它不是“开箱即用”的魔法，必须满足两个硬性前提：声明 color-scheme，且值中需包含对应模式。
为什么写 light-dark(#333, #fff) 却没生效
最常见原因是缺失 color-scheme 声明。浏览器不会凭空推断你“想适配系统主题”，它只看 :root 或宿主元素是否显式声明了支持的方案。没有 color-scheme: light dark，light-dark() 直接退化为无效值（计算为 unset），不报错也不渲染。
- 必须写在
:root或目标元素上：:root { color-scheme: light dark; } - 值必须是空格分隔的关键词，不能是变量或表达式：
color-scheme: var(--scheme)❌ 不生效 - 若只写
color-scheme: dark，则light-dark()永远取第二个参数（暗色），忽略系统偏好 - 该函数仅作用于**颜色值**（
color、background-color、border-color等），不能用于font-size或display
light-dark() 和 @media (prefers-color-scheme) 能否混用
可以，但要理解分工：媒体查询控制**全局逻辑分支**，light-dark() 是**属性级快捷语法**。两者不冲突，但混用时容易重复覆盖。
- 推荐纯 CSS 场景下优先用
light-dark()替代手写媒体查询块，减少冗余 - 若已有大量
@media块，不要把light-dark()塞进里面——它本身已内建逻辑，嵌套会导致不可预测行为 - JS 动态切换主题时，
light-dark()仍会响应系统变化；但若你用 JS 强制加class="theme-dark"覆盖，它就失效了（此时应改用 CSS 变量 + class 切换） - 兼容旧浏览器？别依赖降级：未支持浏览器直接忽略该函数，需另配
@supports (color: light-dark(black, white))做渐进增强
实际项目中怎么组织变量才不踩坑
把 light-dark() 当作“原子色值”来用，而不是主题开关。它适合定义基础 token，不适合做复杂逻辑。
立即学习“前端免费学习笔记（深入）”；
- 正确姿势：在
:root里定义语义化变量，值直接是light-dark()：--text-primary: light-dark(#1f2937, #e5e7eb); - 错误姿势：试图在
@media里重设变量值为light-dark()—— 变量本身已含逻辑，再套一层无意义 - 图片、渐变、阴影等非纯色场景不适用：目前
light-dark()**只接受<color></color>类型参数**，不能写light-dark(url(…), url(…))或light-dark(rgba(0,0,0,0.1), …) - 性能无额外开销：它是声明期解析，不触发重排重绘，比 JS 监听
prefers-color-scheme更轻量
真正容易被忽略的是：它不解决“用户手动切换主题”的需求。如果你提供「白天/黑夜/自动」三档开关，light-dark() 只管“自动”那一档；另外两档必须靠 class 或 CSS 变量手动控制——别指望一个函数包打天下。
