最安全的 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 图标颜色。
-
colorPrimary、borderRadius、fontSize属于 Seed Token，改它们会自动影响整套组件 - 想局部调整（如仅让
Select下拉菜单圆角变小），应走theme.components.Select配置，而不是覆盖.ant-select-dropdown - 浏览器开发者工具里看到的
var(--ant-color-primary)就是可覆盖点，别再查源码找具体像素值
需要改 DOM 结构级样式时，必须加作用域限制
当 Design Token 无法满足需求（例如给 Select 多选框加滚动高度限制、调整 Modal body 内边距），就得写 CSS。但直接写 .ant-select-selection 是危险的——它会全局生效，影响所有 Select 实例。
Vue 用户用 :deep()，React 用户靠 className + :global() 或 CSS Modules 的 compose，核心逻辑一致：先挂载唯一 class，再限定作用域。
立即学习“前端免费学习笔记（深入）”；
- React 示例：
<Select className="my-select-wrapper" />，然后在 CSS 里写.my-select-wrapper :global(.ant-select-selection) { max-height: 40px; overflow-y: auto; } - Vue 示例：
<div class="my-modal"><Modal /></div>，配合:deep(.ant-modal-body) { padding: 12px; } - 千万别省略 wrapper class——没有它，
:global就等于全局污染
慎用 !important，且必须带注释
Ant Design 5 的 CSS-in-JS 生成的样式有很高特异性（比如 [data-ant-id="xxx"] .ant-btn），普通选择器很难压过它。这时候有人会本能加 !important，但这是最后手段。
它会破坏 token 的响应式更新逻辑——比如你强制设了 background: red !important，后续通过 ConfigProvider 切换主题时，这个红色不会跟着变。
- 只在极少数场景下允许：比如第三方插件注入的 inline style、iframe 内嵌内容、或 Web Component shadow boundary 外部穿透
- 每次使用必须紧跟注释，说明「为何此处无法用 token 或 scoped 方案」，例如：
/* HACK: antd Modal title icon has no token, must override */ - 上线前用 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 是否仍存在、是否被新类名替代。
- 把覆盖样式集中放在单独文件（如
antd-overrides.css），并加注释标明适配的版本号 - CI 流程中加入视觉回归测试（如 Chromatic），比人工点开每个页面更可靠
- 如果发现某组件结构频繁变动（如
DatePicker），优先考虑封装一层业务组件，把样式逻辑收束到内部，而非外部覆盖
