Antd v5：ConfigProvider自定义CSS变量的正确用法及生效问题

原因分析 #

• Ant Design的ConfigProvider会给包裹的组件做主题隔离，靠CSS变量的层级优先级实现。:root是全局最高层级，但ConfigProvider会在内部注入局部CSS变量，优先级比:root的高，只有当某个组件的样式没被ConfigProvider的局部变量覆盖时，才会用:root里的全局令牌。
• 有些组件或层级的样式是直接读取ConfigProvider内部维护的主题变量，不是全局CSS变量，这种情况下:root的定义根本不会生效。

正确使用方法 #

方法1：直接通过ConfigProvider配置主题令牌 #

这是最稳妥的方式，在ConfigProvider的theme里定义或覆盖颜色令牌，所有被包裹的组件都会统一用这些变量，不会有层级覆盖的问题：

import { ConfigProvider } from 'antd';

const App = () => (
  <ConfigProvider
    theme={{
      token: {
        colorPrimary: '#1890ff',
        // 其他需要定义的颜色令牌
      },
    }}
  >
    {/* 你的应用组件 */}
  </ConfigProvider>
);

方法2：全局CSS变量配合ConfigProvider的cssVar模式 #

如果想保留:root的全局定义，打开ConfigProvider的cssVar模式，让组件优先读取全局CSS变量：

import { ConfigProvider } from 'antd';

const App = () => (
  <ConfigProvider
    theme={{
      cssVar: true,
    }}
  >
    {/* 你的应用组件 */}
  </ConfigProvider>
);

然后在全局样式文件里这样定义：

:root {
  --ant-color-primary: #1890ff;
  /* 要对应Ant Design的CSS变量命名规则，比如token里的colorPrimary对应--ant-color-primary */
}

方法3：给特定层级单独覆盖 #

如果只需要在某部分组件里生效，可以在父元素上定义CSS变量，它的优先级比:root高，还能覆盖ConfigProvider的局部变量：

.custom-section {
  --ant-color-primary: #2f54eb;
}

然后把需要改的组件放在这个容器里：

<div className="custom-section">
  <Button type="primary">自定义颜色的按钮</Button>
</div>

内容的提问来源于stack exchange，提问作者Rey Wang