CSS light-dark() 函數完全攻略：一行程式碼搞定原生暗色模式切換

什麼是 CSS light-dark()？為什麼它是遊戲規則改變者

說到暗色模式，大部分前端開發者的第一反應就是 @media (prefers-color-scheme: dark)。這個方法沒什麼問題，但寫起來真的很煩——每個變數都要寫兩次，深色一次淺色一次，樣式表瀏間就膨脹了。

light-dark() 函數的出現徹底解決了這個痛點。它讓你在同一行 CSS 中同時定義淺色和深色模式的值，瀏覽器會根據使用者的系統設定自動選擇正確的那一個。

:root {
  color-scheme: light dark;
}

body {
  color: light-dark(#333b3c, #efefec);
  background-color: light-dark(#efedea, #223a2c);
}

就這樣。不需要寫任何 media query，不需要寫 JavaScript，三行 CSS 就搞定了完整的深淺色切換。

運作原理：color-scheme + light-dark()

要讓 light-dark() 運作，有一個前提條件：你必須先設定 color-scheme 屬性。

:root {
  color-scheme: light dark;  /* 要告訴瀏覽器你支援兩種模式 */
}

這行程式碼告訴瀏覽器：「我的網站同時支援淺色和深色模式」。瀏覽器會根據使用者的系統設定決定用哪一個。

如果你只寫 color-scheme: light，那 light-dark() 永遠只會返回第一個值。同理，color-scheme: dark 永遠只會返回第二個值。

與 prefers-color-scheme 的比較

傳統方法：

:root {
  --bg: #ffffff;
  --text: #333333;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #1a1a1a;
    --text: #eeeeee;
  }
}

新方法：

:root {
  color-scheme: light dark;
  --bg: light-dark(#ffffff, #1a1a1a);
  --text: light-dark(#333333, #eeeeee);
}

差異很明顯：新方法只需要宫告一次變數，淺深色值並排在一起，可讀性和維護性都好很多。

搭配 color-mix() 打造精細色彩控制

light-dark() 不只接受純色彩值，它還可以搭配 color-mix() 做更精細的調色：

.card {
  background-color: light-dark(
    var(--gray-100),
    color-mix(in oklch, var(--gray-900) 90%, var(--blue-900))
  );
}

這樣在淺色模式下用純灰色，在深色模式下則用灰色混合一點藍色，讓暗色主題不會太沉悶。這種精細調色在以前需要寫很多程式碼，現在一行就損定。

如果你對 CSS 新功能有興趣，可以看看CSS :has() 選擇器和CSS @scope 原生作用域的教學。

2026 新功能：圖片切換支援

之前 light-dark() 有一個明顯的限制：只能用於色彩值。如果你想根據深淺色切換 Logo 或背景圖，還是得用傳統方法。

好消息是，2026 年規範已經更新，light-dark() 正在擴展支援圖片切換！這個功能已經可以在 Chromium 148+ 的 Experimental Web Platform Features 旗標中使用。

但要注意：你必須傳入兩個色彩值或兩個圖片值，不能混合類型。

瀏覽器支援狀態

截至 2026 年 3 月：

• Chrome 123+：完全支援
• Firefox 120+：完全支援
• Safari 17.5+：完全支援
• Edge 123+：完全支援

已經是 Baseline Widely Available 的狀態，可以安心在生產環境使用。

實戰：完整的暗色模式實作

:root {
  color-scheme: light dark;

  /* 基礎色彩 */
  --bg-primary: light-dark(#ffffff, #0f0f0f);
  --bg-secondary: light-dark(#f5f5f5, #1a1a1a);
  --text-primary: light-dark(#1a1a1a, #f0f0f0);
  --text-secondary: light-dark(#666666, #999999);
  --border: light-dark(#e0e0e0, #333333);
  --accent: light-dark(#0066cc, #4da6ff);

  /* 陰影 */
  --shadow: light-dark(
    0 2px 8px rgba(0,0,0,0.1),
    0 2px 8px rgba(0,0,0,0.5)
  );
}

body {
  background: var(--bg-primary);
  color: var(--text-primary);
}

.card {
  background: var(--bg-secondary);
  border: 1px solid var(--border);
  box-shadow: var(--shadow);
}

這套變數系統簡潔又完整，維護起來也很輕鬆。配合CSS Popover API 等原生功能，你可以用純 CSS 建立出非常完整的 UI 系統。

限制與注意事項

• 目前只支援兩種配色方案（淺/深），不支援第三種方案（如「高對比」）
• W3C 正在考慮擴展以支援更多配色方案和非色彩屬性
• 圖片切換功能還在實驗階段，生產環境建議先用 @media 做回退

總結：原生暗色模式的最佳實踐

light-dark() 是 CSS 近年來最實用的新函數之一。它大幅簡化了暗色模式的實作，讓深淺色值並排在一起，提高可讀性和維護性。搭配 color-mix() 更能精細調控深色主題的色彩。現在就開始用吧！