跳到主要内容

Docusaurus热加载custom.css样式失效问题

· 阅读需 3 分钟

custom.css 是用 Tailwind CSS v4 语法写的（@layer theme, base…、@theme、@plugin、@custom-variant 等）， 但 Docusaurus 官方只内置了 PostCSS + Tailwind CSS v3 的管线。 直接把 v4 语法丢进去，PostCSS 会全部跳过，于是出现“样式怎么改都不热加载 / 不生效”的现象。

核心问题​

  1. Tailwind v4 需要全新的引擎（@tailwindcss/cli 或 Vite/Webpack 插件）， 旧的 tailwindcss@3 + postcss-import 无法识别新语法。
  2. 你当前只是通过 postcssOptions.plugins.unshift(require('@tailwindcss/postcss')) 把 v4 的 PostCSS 插件塞进去， 但它不会自动替你解析 v4 的 @theme、@plugin 等新指令，结果整个文件被当成普通 CSS， 导致：
    • 热加载“看上去”没反应（其实文件被 PostCSS 抛弃）；
    • 页面也看不到任何 Tailwind 类生效。

解决方案（二选一）​

✅ 方案 A：退回 Tailwind CSS v3（最省事，官方路线）​

  1. 卸载 v4 相关包

    npm uninstall @tailwindcss/postcss tailwindcss

    ​

  2. 装回 v3

    npm i -D tailwindcss@3 postcss-import autoprefixer

    ​

  3. 把 custom.css 里所有 v4 语法全部改成 v3 写法：

    • 删掉

      @layer theme, base, components, utilities;
      @import 'tailwindcss/theme.css' layer(theme) important;
      @import 'tailwindcss/utilities.css' layer(utilities) important;
      @plugin 'tailwindcss-animate';
      @custom-variant dark (&:is([data-theme="dark"] *));
      @theme inline { … }

      ​

    • 恢复成 v3 的标准引入

      @tailwind base;
      @tailwind components;
      @tailwind utilities;

      ​

    • 把 @theme 里的变量搬到 tailwind.config.js 的 theme.extend 里； 把 @custom-variant dark 换成 darkMode: ['class', '[data-theme="dark"]'] + 自定义 variant。

    • 插件（tailwindcss-animate）在 tailwind.config.js 里 require() 进来即可。

  4. 重启

    npm start

    ​

    此时热加载会恢复正常，页面也能正确读到样式。

✅ 方案 B：升级整个构建管线到 Tailwind CSS v4（实验性）​

Docusaurus 目前还没有官方 v4 插件，需要你自己把 Tailwind CLI 接进来，步骤如下：

  1. 保留 v4 依赖

    npm i -D @tailwindcss/cli

    ​

  2. 新建 tailwind.styles.css（只放 v4 语法），不要放在 src/css/custom.css：

    src/tailwind.styles.css   ← 写你贴的那段 v4 代码

    ​

  3. 在 package.json 里加一条实时编译脚本

    "scripts": {
      "tw:watch": "tailwindcss -i ./src/tailwind.styles.css -o ./src/css/tailwind.out.css --watch"
    }

    ​

  4. 改 docusaurus.config.js，让 customCss 只引用编译后的文件：

    customCss: ['./src/css/tailwind.out.css', './src/css/custom.css'],

    ​

  5. 开两个终端

    # 终端 1
    npm run tw:watch

    # 终端 2
    npm start

    ​

    这样 Tailwind v4 会实时把结果写到 tailwind.out.css， Docusaurus 再对 tailwind.out.css 做热加载，页面生效且 HMR 正常。

一句话总结​

  • 想用 v4 语法 → 必须走 Tailwind 自己的编译器（方案 B）。
  • 想继续用 Docusaurus 默认管线 → 退回 v3 写法（方案 A）。

按上面任一方案改完，保存即热加载的问题就会消失。 如果还有细节报错，把终端信息贴给我，我继续帮你盯。