业务背景
接着上一篇的现状:平台里大量多年运行的存量系统,jQuery / Vue / React 混杂,需要使用最小的改动完成本次系统之间的集成。
Ant Design 默认输出 ant-* 全局类名。qiankun 环境里多个子应用共用 document,几套 antd 的样式就开始互相污染。
antd 5 提供了 ConfigProvider 的 prefixCls,可以改组件运行时输出到 DOM 的类名。但只配这个参数是不够的:因为项目里还引了设计系统主题包,主题包 CSS 和部分 ProComponents 内部的硬编码字符串依然写死 .ant-*,这部分 prefixCls 管不到。
最终方案是两条腿走路:ConfigProvider 改运行时类名 + 构建期 loader 改写静态资源。
系列文章
- 总览篇:qiankun 微前端:放弃官方样式隔离,我们落地了 3 套构建期解决方案
- 第三篇:AG-Grid 在 qiankun 下的 CSS 命名空间隔离
- 第四篇:qiankun 主题隔离,把 data-theme 从 html 挪进自己的容器
实现思路
- 运行时:全局
ConfigProvider设置prefixCls="sub-a",组件 DOM 输出变成sub-a-btn、sub-a-modal; - 构建期:自定义 loader 挂在 CSS 解析链前面,把静态 CSS、JS/TS 字符串里的
.ant-*、'ant-xxx'全部替换成新前缀。
loader 只是正则文本替换,不分注释边界,注释里命中规则的字符串也会被替换;运行时拼接的类名依旧处理不了。
如果项目已经很成熟,那么就直接使用自定义loader,在构建的时候,进行整体的替换,这样对代码的改动点很小。
实现步骤
1. 全局配置 ConfigProvider
在应用根组件挂一次即可,控制组件运行时输出的类名前缀。
import { ConfigProvider } from 'antd';
import zhCN from 'antd/locale/zh_CN';
function App() {
return (
<ConfigProvider locale={zhCN} prefixCls="sub-a">
{/* 业务应用入口 */}
</ConfigProvider>
);
}
如果项目没引第三方主题包,也没有大量手写的
.ant-*覆盖样式,到这一步就够了,后面的 loader 不用配。
2. 编写自定义 loader
新建 loaders/replace-ant-prefix-loader.js:
// loaders/replace-ant-prefix-loader.js
const FROM = 'ant';
const TO = 'sub-a';
module.exports = function replaceAntPrefixLoader(source) {
// CSS 选择器:.ant-btn -> .sub-a-btn
let result = source.replace(
new RegExp(`\\.${FROM}-([a-zA-Z0-9_-]+)`, 'g'),
`.${TO}-$1`,
);
// JS 字面量字符串:'ant-tabs' -> 'sub-a-tabs',"ant-select" -> "sub-a-select"
result = result.replace(
new RegExp(`(['"])${FROM}-([a-zA-Z0-9_-]+)\\1`, 'g'),
(_match, quote, name) => `${quote}${TO}-${name}${quote}`,
);
return result;
};
3. 注册 loader
rsbuild.config.ts 里追加一条规则。注意 import path,enforce: 'pre' 必须加,保证在 CSS 解析之前执行。
import path from 'path';
// 在 tools.rspack 里追加
config.module.rules.push({
test: /\.(js|jsx|ts|tsx|css|less)$/,
include: [
path.resolve(__dirname, 'src'),
// 会输出 .ant-* 的业务设计系统包,必须一起处理
/node_modules[\\/]@your-ds/,
],
enforce: 'pre',
use: [
{
loader: path.resolve(__dirname, 'loaders/replace-ant-prefix-loader.js'),
},
],
});
三个参数各自的意义:
enforce: 'pre':必须早于 CSS 解析链,否则选择器已经进 AST,字符串替换改不动;test带js|jsx|ts|tsx:组件包把类名写在 JS 字符串里,只处理 CSS 是不够的;include覆盖全部来源:漏一个包,等于没做。
4. 业务样式怎么写
loader 会自动改写源码里的 .ant-*,所以业务代码继续按 antd 官方类名写就行,构建后自动换成新前缀:
export default createStyles(({ css }) => ({
modal: css`
.ant-modal-content {
border-radius: 4px;
}
`,
}));
构建产物里会变成 .sub-a-modal-content。也可以直接写 .sub-a-*,loader 不会重复处理。建议团队统一一种写法,别在同一个文件里两种前缀混着来。
生产环境踩坑记录
坑 1:只配 prefixCls,没配 loader
现象:组件本体样式正常,主题色、圆角、间距全不对。
原因:prefixCls 只改运行时 DOM,改不到第三方包里写死的静态 CSS。DOM 上已经是 .sub-a-btn,主题包里的 .ant-btn { ... } 自然匹配不上。
坑 2:include 漏了设计系统包
现象:页面看着「没套主题」。
原因:include 只写了 src,node_modules 下主题包的 CSS 没进 loader。
坑 3:ProComponents 部分组件样式失效
有些类名写在 JS 字符串字面量里,如果 loader 只处理 css 文件,JS 根本不会被改写。
所以
test一定要带上 js / ts / tsx。
坑 4:rc-* 底层包不用处理
rc-select、rc-picker 里的 ant- 大多是注释里的 issue 链接,真实类名是 antd 通过 prefixCls 参数传进去的,不需要纳入 include。
验证一下:
grep -rn "ant-" node_modules/rc-select/es/*.js | grep -v "github.com"
坑 5:anticon 图标类名不会被替换
正则匹配的是 .ant-,anticon 没有连字符,命中不了。这是有意保留的:图标类名冲突概率低,antd 内部还依赖它注入图标样式。强行替换要同步改图标注入逻辑,风险大于收益。
坑 6:正则版 loader 的两个短板
- 注释会被误伤:
/* .ant-btn 示例 */里的文本也会被替换,不影响运行但会干扰 grep 排查; - 动态拼接抓不到:
const cls = 'ant-' + size这种运行时拼接,任何静态 loader 都无能为力,只能靠prefixCls统一入口。
真要求「只改选择器」,CSS 部分换成 PostCSS 解析:
const postcss = require('postcss');
module.exports = function (source) {
const root = postcss.parse(source);
root.walkRules((rule) => {
rule.selector = rule.selector.replace(/\.ant-/g, '.sub-a-');
});
return root.toString();
};
代价是多一个依赖,含 Less 语法(变量、嵌套)的文件还得传 postcss-less 当 parser;JS 侧继续用字符串正则。CSS 走 PostCSS、JS 走正则,性价比最高。
构建产物校验
构建完跑一个脚本,把「有没有残留」变成可量化的数字,别靠肉眼。
保存为 check-ant-prefix.js,在项目根目录执行 node check-ant-prefix.js。
const fs = require('fs');
const path = require('path');
const DIST = 'dist';
function walk(dir) {
return fs.readdirSync(dir).flatMap((name) => {
const full = path.join(dir, name);
return fs.statSync(full).isDirectory() ? walk(full) : [full];
});
}
let residual = 0;
let renamed = 0;
for (const file of walk(DIST)) {
if (!/\.(css|js)$/.test(file)) continue;
const raw = fs.readFileSync(file, 'utf8');
// 去掉注释和 URL,避免把 issue 链接算成残留
const cleaned = raw.replace(/\/\*[\s\S]*?\*\/|github\.com\S*/g, '');
residual += (cleaned.match(/\.ant-[a-z]/g) || []).length;
renamed += (cleaned.match(/\.sub-a-[a-z]/g) || []).length;
}
console.log('.ant- 残留:', residual, '(必须为 0)');
console.log('.sub-a- 命中:', renamed, '(必须大于 0)');
浏览器侧再确认一遍类名:
- Button →
sub-a-btn - Modal →
sub-a-modal - Table →
sub-a-table - DatePicker →
sub-a-picker - 图标 →
anticon(保持不变) - 多子应用同时运行,互不影响
业务开发注意事项
- 写覆盖样式继续写官方
.ant-*,交给 loader 处理,别一半手写一半自动; - 新增第三方包,先确认它是否输出
.ant-*,再决定要不要加进include; - 升级 antd 或主题包,重跑校验脚本,重点看残留是不是 0;
- loader 只管构建期静态源码,JS 动态拼类名的场景要业务自己兜。