如何使用Ant Design 5覆盖组件CSS样式

最安全的 Ant Design 5 样式覆盖方式是通过 ConfigProvider 的 theme.token 修改设计变量，而非直接写 CSS 类名；需优先使用 Seed Token（如 colorPrimary）和 Component Token（如 theme.components.Select），局部覆盖必须加 wrapper class 限定作用域，慎用 !important 并注释原因，升级时重点检查 DOM 结构变动。

直接用 CSS 变量覆盖最安全

Ant Design 5 默认启用 CSS-in-JS，但真正推荐的覆盖方式不是写 .ant-button 这类选择器，而是通过 ConfigProvider 的 theme.token 修改设计变量。它不破坏框架样式结构，升级时也极少断裂。

常见错误是试图用全局类名覆盖却忽略变量派生关系——比如只改 colorPrimary，但按钮背景、边框、hover 色其实由它派生而来，改一个就全生效；而硬写 .ant-btn-primary { background: #xxx } 反而容易漏掉 disabled 状态或 loading 图标颜色。

1. colorPrimary、borderRadius、fontSize 属于 Seed Token，改它们会自动影响整套组件
2. 想局部调整（如仅让 Select 下拉菜单圆角变小），应走 theme.components.Select 配置，而不是覆盖 .ant-select-dropdown
3. 浏览器开发者工具里看到的 var(--ant-color-primary) 就是可覆盖点，别再查源码找具体像素值

需要改 DOM 结构级样式时，必须加作用域限制

当 Design Token 无法满足需求（例如给 Select 多选框加滚动高度限制、调整 Modal body 内边距），就得写 CSS。但直接写 .ant-select-selection 是危险的——它会全局生效，影响所有 Select 实例。

Vue 用户用 :deep()，React 用户靠 className + :global() 或 CSS Modules 的 compose，核心逻辑一致：先挂载唯一 class，再限定作用域。

1. React 示例：<Select className="my-select-wrapper" />，然后在 CSS 里写 .my-select-wrapper :global(.ant-select-selection) { max-height: 40px; overflow-y: auto; }
2. Vue 示例：<div class="my-modal"><Modal /></div>，配合 :deep(.ant-modal-body) { padding: 12px; }
3. 千万别省略 wrapper class——没有它，:global 就等于全局污染

慎用 !important，且必须带注释

Ant Design 5 的 CSS-in-JS 生成的样式有很高特异性（比如 [data-ant-id="xxx"] .ant-btn），普通选择器很难压过它。这时候有人会本能加 !important，但这是最后手段。

它会破坏 token 的响应式更新逻辑——比如你强制设了 background: red !important，后续通过 ConfigProvider 切换主题时，这个红色不会跟着变。

1. 只在极少数场景下允许：比如第三方插件注入的 inline style、iframe 内嵌内容、或 Web Component shadow boundary 外部穿透
2. 每次使用必须紧跟注释，说明「为何此处无法用 token 或 scoped 方案」，例如：/* HACK: antd Modal title icon has no token, must override */
3. 上线前用 DevTools 检查是否仍有未被覆盖的 !important 堆叠，避免优先级雪崩

升级 Ant Design 时，CSS 覆盖最容易失效

Ant Design 5.x 各小版本之间，组件内部 DOM 结构和类名可能微调（比如 .ant-table-thead → .ant-table-container .ant-table-thead），但 Design Token 接口基本稳定。这意味着你写的 CSS 覆盖越细，越容易在 5.12.0 → 5.13.0 升级后突然失效。

真正要检查的不是样式是否“看起来一样”，而是是否还精准命中目标节点——打开 DevTools，逐层展开组件 DOM，确认你写的 .my-wrapper :global(.xxx) 里的 .xxx 是否仍存在、是否被新类名替代。

1. 把覆盖样式集中放在单独文件（如 antd-overrides.css），并加注释标明适配的版本号
2. CI 流程中加入视觉回归测试（如 Chromatic），比人工点开每个页面更可靠
3. 如果发现某组件结构频繁变动（如 DatePicker），优先考虑封装一层业务组件，把样式逻辑收束到内部，而非外部覆盖