Next.js 中 Tailwind v4 的深浅模式切换

2025年5月12日

一、前言

Tailwind CSS v4 进行了一次大更新，之前 v3 的 dark mode 设置方式已经不再适用。但好消息是，v4 优化了 dark mode 的使用，现在能更加简单地为网站设置深浅模式。

二、使用 Tailwind v4 新设置

1、首先安装 tailwind v4，官方推荐使用 PostCSS 插件将 tailwind 集成到 next.js 中。（参考tailwind官网）

安装步骤：
（1）先通过 npm 等管理工具安装

npm install tailwindcss @tailwindcss/postcss postcss

（2）然后在postcss.config.mjs文件中配置 tailwind：

//postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

（3）最后在global.css文件里导入 Tailwind 即可。

@import "tailwindcss";

现在可以使用 Tailwind CSS 了！

2、手动创建深色模式：

创建步骤：
（1）绑定 dark 模式：在global.css中进行以下配置

@custom-variant dark (&:where(.dark, .dark *));

此时 dark mode 应用将基于 dark 类。

（2）在任意元素中使用dark变体：

<span class="text-black dark:text-white">dark mode</span>

（3）控制<html>标签的 dark 类，以决定是否启用深色模式。当<html>具有 dark 类时，所有元素会使用 dark 变体，以替代原本的样式。

<html class="dark">
  <body>
    <span class="text-black dark:text-white">dark mode</span>
  </body>
</html>

（4）你可以通过 React 来控制添加和删除 dark 类，实现深色模式和浅色模式的切换。这里的localStorage.setItem("theme", ... )用于将主题存储到浏览器本地，这样可以缓存用户使用的主题。

export default function Page() {
  const [mode, setMode] = useState("");

  useEffect(() => {
    const saved = localStorage.getItem("theme") || "";
    setMode(saved);
    document.documentElement.classList = saved;
  }, []);

  function changemode() {
    const newmode = mode === "" ? "dark" : "";
    setMode(newmode);
    document.documentElement.classList = newmode;
    localStorage.setItem("theme", newmode);
  }

  return (
    <div className="flex items-center w-36 h-20 bg-amber-100 dark:bg-black">
      <span className="text-black dark:text-white">dark mode</span>
      <button
        className="bg-amber-200 text-black dark:bg-gray-600 dark:text-white"
        onClick={changemode}
      >
        change
      </button>
    </div>
  );
}

三、额外的

如果你有两个颜色模版文件，例如 Google 的 MD3 规范配色方案，你也可以通过控制导入的颜色模版来控制使用的模式。

相关步骤：
（1）颜色模版示例：

/*light.css*/
.light {
  --md-sys-color-background: #fafdfc;
  --md-sys-color-on-background: #191c1c;
}

/*dark.css*/
.dark {
  --md-sys-color-background: #191c1c;
  --md-sys-color-on-background: #e0e3e2;
}

（2）将模版导入 tailwind 主题（当然，你直接用 CSS 变量也可以）

/*global.css*/
@theme {
  --color-background: var(--md-sys-color-background);
  --color-on-background: var(--md-sys-color-on-background);
}

（3）然后应用相关主题变量

<div className="bg-color-background"></div>

（4）使用 React 控制<html>标签的类来控制导入的颜色模版，以实现不同主题的切换。

<html class="light"></html>
<html class="dark"></html>

Next.js 中 Tailwind v4 的深浅模式切换

一、前言

二、使用 Tailwind v4 新设置

三、额外的

目录