Tailwind CSS v4 + Antd v6 + Umi Max 兼容方案

技术栈版本

依赖	版本
antd	^6.3.1
@ant-design/cssinjs	^2.1.0
@ant-design/pro-components	3.1.9-0
@umijs/max	^4.6.29
tailwindcss	^4
@tailwindcss/postcss	^4

核心问题

Tailwind CSS v4 和 Antd v6 都使用了 CSS @layer 来管理样式优先级，但在 Umi Max 项目中集成时会遇到三个严重的样式冲突问题。

问题 1：@layer 声明顺序被 CSS-in-JS 抢占

现象：首页刷新后 antd 组件样式全部丢失（按钮没有背景色、输入框没有边框等），但 SPA 导航时正常。

根因：

CSS @layer 的优先级由第一次出现的顺序决定（越靠后优先级越高）。@ant-design/cssinjs 在启用 layer 模式后会将 antd 的 <style> 标签以 prepend: true 方式插入到 <head> 最前面，例如：

<head>
  <!-- CSS-in-JS 抢先 prepend，@layer antd 变成第一个被声明 -->
  <style data-rc-order="prepend">@layer antd { .anticon { ... } }</style>

  <!-- 我们声明的顺序在后面，但 antd 已经是 position 1 了 -->
  <style>@layer theme, base, antd, antd-pro, components, utilities;</style>

  <!-- Tailwind 的 @layer base 声明在 antd 之后，优先级反而更高 -->
  <link href="/umi.css" />  <!-- 包含 @layer base { *, *::before... margin:0; padding:0; } -->
</head>

实际层级变成了：

antd       ← 最低优先级！（第一个出现）
theme
base       ← Tailwind preflight 在这里，优先级高于 antd
antd-pro
components
utilities  ← 最高优先级

Tailwind preflight 的 margin: 0; padding: 0; border: 0 solid; 等重置样式覆盖了所有 antd 组件。

问题 2：antd/dist/reset.css 未分层

Umi 的 antd 插件会自动引入 antd/dist/reset.css（246 行的 CSS 重置），这些样式是 unlayered 的。在 CSS 规范中，未分层样式永远优先于任何 @layer 内的样式。

问题 3：`@import 'tailwindcss'` 自带 @layer 声明

Tailwind v4 的 index.css 内部包含 @layer theme, base, components, utilities;（不含 antd），直接 @import 'tailwindcss' 会在 global.css 中注入另一份 layer 声明，可能干扰顺序。

问题 4：Umi antd 插件不支持 `styleProvider.layer`

Umi 的 antd 插件模板（runtime.ts.tpl）只处理了 hashPriority 和 legacyTransformer，不会渲染 layer prop。即使配置了 antd: { styleProvider: { layer: true } }，生成的 <StyleProvider> 也不会有 layer 属性。

问题 5：MFSU 缓存问题

Umi 的 MFSU（Module Federation Speed Up）可能缓存旧版本的 @ant-design/cssinjs 和 antd/dist/reset.css，导致改动不生效。

解决方案

整体思路

[HTML <head>]
  ┌─ <style>@layer theme, base, antd, antd-pro, components, utilities;</style>  ← config.ts styles 注入，最先出现
  ├─ <link href="umi.css" />  ← Tailwind 样式（@layer theme/base/utilities）
  ├─ <link href="Layout.chunk.css" />  ← Umi Layout 样式
  └─ <div id="antd-cssinjs-container">  ← CSS-in-JS 容器，追加在末尾
      ├─ <style>@layer antd { .ant-btn { ... } }</style>
      ├─ <style>@layer antd-pro { .ant-pro-layout { ... } }</style>
      └─ ...

1. config/config.ts — 注入 @layer 顺序声明 + 替换 reset.css

import { defineConfig } from '@umijs/max'
import routes from './routes/index'

export default defineConfig({
  antd: {},
  access: {},
  model: {},
  initialState: {},
  request: {},
  layout: {},
  routes,
  npmClient: 'pnpm',
  // 确保 @layer 声明在 HTML <head> 中最先出现
  styles: [`@layer theme, base, antd, antd-pro, components, utilities;`],
  // 将 antd 的 reset.css 替换为空文件（Tailwind preflight 已包含 CSS 重置）
  alias: {
    'antd/dist/reset.css': require.resolve('../src/antd-reset-layer.css'),
  },
  // 临时禁用 MFSU，避免缓存干扰样式
  mfsu: false,
})

关键配置说明：

styles：在 HTML 模板中注入 <style> 标签，保证 @layer 声明顺序在所有其他样式之前。这决定了层级优先级从低到高：theme < base < antd < antd-pro < components < utilities
alias：将 antd/dist/reset.css 重定向到空文件，避免 unlayered 的重置样式覆盖分层样式。Tailwind v4 的 preflight 已经包含了完整的 CSS 重置
mfsu: false：禁用 MFSU 避免缓存导致的样式问题

2. src/antd-reset-layer.css — 空文件替代 antd reset

/* antd/dist/reset.css 被此空文件替代 */
/* Tailwind v4 preflight 已包含完整的 CSS 重置 */

3. src/global.css — Tailwind 细粒度导入

@layer theme, base, antd, antd-pro, components, utilities;

/* Tailwind v4 细粒度导入，精确控制各层所在 layer */
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import 'tailwindcss/utilities.css' layer(utilities);

@import url('./allahjs-antd/styles/index.less');

为什么不用 @import 'tailwindcss'：

Tailwind v4 的 index.css 内部自带 @layer theme, base, components, utilities; 声明（不含 antd 和 antd-pro），可能干扰我们的 layer 顺序。使用细粒度导入 + layer() 参数可以精确控制每个部分归属哪个 layer。

4. src/app.tsx — StyleProvider + container 隔离

import { StyleProvider } from '@ant-design/cssinjs'

/**
 * CSS-in-JS 样式容器
 *
 * 核心问题：@ant-design/cssinjs 的 prepend:true 会将 @layer antd {...}
 * 插入到 <head> 最前面，导致 antd layer 被首先声明，优先级变为最低。
 *
 * 解决方案：创建一个 <div> 容器追加到 <head> 末尾，
 * 让所有 CSS-in-JS 的 <style> 标签在此容器内 prepend/append，
 * 不影响之前的 @layer 顺序声明。
 */
let _cssinjsContainer: HTMLElement | undefined
function getCSSInjsContainer(): HTMLElement | undefined {
  if (typeof document === 'undefined') return undefined
  if (_cssinjsContainer) return _cssinjsContainer
  const id = 'antd-cssinjs-container'
  let el = document.getElementById(id) as HTMLElement
  if (!el) {
    el = document.createElement('div')
    el.id = id
    document.head.appendChild(el)
  }
  _cssinjsContainer = el
  return el
}

export function rootContainer(container: React.ReactNode) {
  return (
    <StyleProvider layer container={getCSSInjsContainer()}>
      {container}
    </StyleProvider>
  )
}

StyleProvider 的两个关键 prop：

layer：让 antd 的 CSS-in-JS 样式包裹在 @layer antd { ... } 中，降权以允许 Tailwind utilities 覆盖
container：将所有 <style> 标签注入到 <head> 末尾的容器中，避免 prepend:true 抢占 @layer 声明顺序

5. postcss.config.js

module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

6. tailwind.config.js

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.tsx'],
}

CSS @layer 优先级说明

最终的 layer 优先级（从低到高）：

Layer	内容	说明
`theme`	Tailwind CSS 变量	`--color-*`, `--spacing` 等设计 token
`base`	Tailwind preflight	CSS 重置：`margin:0; padding:0; border:0;` 等
`antd`	Antd v6 组件样式	Button、Input、Table 等所有 antd 组件
`antd-pro`	ProComponents 样式	ProLayout、ProTable、PageContainer 等
`components`	自定义组件样式	项目中的自定义组件 CSS
`utilities`	Tailwind 工具类	`text-red-500`、`p-4`、`flex` 等（最高优先级）

使用规则：

Tailwind 工具类（如 className="text-red-500 p-4"）可以直接覆盖 antd 默认样式，不需要 !important
antd 组件样式优先于 Tailwind preflight 重置，组件不会被重置破坏
如需在自定义 CSS 中覆盖 antd，放入 @layer components 中

常见问题排查

Q: 修改配置后样式不生效？

清除所有缓存重启：

rm -rf src/.umi node_modules/.cache
npm run dev

Q: antd 样式丢失（所有组件没有样式）？

用浏览器 DevTools 检查 <head> 中第一个 <style> 标签：

如果第一个是 @layer antd { ... }（而不是 @layer theme, base, antd, ...;），说明 container 隔离没有生效
确认 StyleProvider 的 container prop 是否正确传入

Q: Tailwind 工具类不生效？

检查 <StyleProvider layer> 中的 layer prop 是否存在。没有 layer，antd 样式是 unlayered 的，永远优先于任何 @layer 内的样式。

Q: dev 和 build 行为不一致？

检查 mfsu 配置。MFSU 可能缓存旧版本的 @ant-design/cssinjs，导致 StyleProvider 的 React Context 和 antd 组件不是同一个实例。临时设置 mfsu: false 排查。

原理深入

Antd v6 的 CSS-in-JS 机制

Antd v6 使用 @ant-design/cssinjs v2 管理样式。每个组件在渲染时调用 useStyleRegister() 动态生成 <style> 标签。

当 StyleProvider 设置了 layer={true} 时：

Context 传递：layer: true 通过 React Context（StyleContext）传递给所有子组件
样式包裹：parseStyle() 将组件样式包裹在 @layer antd { ... } 中
注入行为变化：prepend 从 'queue' 变为 false，<style> 标签以 appendChild 方式插入

Tailwind v4 的 @layer 结构

Tailwind v4 的 @import 'tailwindcss' 展开后包含：

@layer theme { :root { --color-*: ...; --spacing: ...; } }
@layer base { *, ::before, ::after { margin:0; padding:0; border:0 solid; } }
/* @layer components — 用户自定义 */
@layer utilities { .flex { display:flex; } .p-4 { padding:1rem; } ... }

为什么需要 container 隔离

@ant-design/cssinjs 在 enableLayer=true 时，对 @layer 依赖声明（如 @layer antd;）使用 prepend: true 注入到 <head> 最前面确保 layer 依赖在最前面。但这恰好破坏了我们的 @layer 顺序声明。

通过指定 container 为 <head> 末尾的一个 <div>，所有 CSS-in-JS 的 prepend/append 操作都在这个容器内进行，不会影响容器外已有的 <style> 和 <link> 标签的顺序。

Pro-Components 的 layer 名

@ant-design/pro-components 使用 @layer antd-pro 作为 layer 名（与 antd 的 @layer antd 不同），所以 @layer 声明中必须包含 antd-pro。

Tailwind CSS v4 + Antd v6 + Umi Max 兼容方案