业务背景
随着业务系统集成化成为大趋势,我们团队引入 qiankun 微前端框架,对公司内部众多独立业务系统做统一接入与管理。 整个微前端平台下并存大量存量业务:包含运行多年的 jQuery 老后台、Vue2/Vue3 搭建的各类中台,以及多个 React 子应用,全部作为 qiankun 子应用共存运行。
这些存量系统已经在线稳定运行多年,业务体量大,如果去修改其他子系统的业务代码、改造组件与样式,改造成本高,周期长,业务使用学习成本高,线上风险不可控。
这些系统在线运行多年,业务体量不小,维护的人也换过几轮。为了样式隔离去改它们的代码、动它们的组件样式,改造成本极高,风险也不可控。
核心约束:为控制迭代成本与线上风险,当前子应用只做适度、可控的局部适配调整,避免大范围、侵入式业务改造,不修改业务逻辑。
一、qiankun 官方样式隔离字段,为什么不用
qiankun 官方提供了两个字段来处理样式隔离,我们两条都试过。
experimentalStyleIsolation:运行时给选择器加前缀
该方案的实现思路:子应用样式表插入页面时,运行时给每一条 CSS 选择器前置追加 div[data‑qiankun="xxx"] 命名空间,以此实现样式隔离。初看刚好可以解决类名污染问题,但落地测试后暴露出较多兼容性问题。
平台内大部分系统原先都是独立站点运行,大量业务样式、组件逻辑并没有考虑微前端容器挂载的特殊场景,由此带来一系列问题:
:root/html/body这类全局根级选择器,追加前缀后选择器语义被破坏,无法正常匹配节点,直接导致主题 CSS 变量、全局重置样式失效;- Modal、Tooltip、Select 下拉等弹窗组件默认挂载至
document.body,脱离子应用 qiankun 容器,不在命名空间作用域内,弹窗样式完全丢失; @font‑face、@keyframes不属于普通 CSS 选择器,无法被该机制处理,容易出现字体、动画异常;- 样式在浏览器运行时实时改写,首屏渲染、弹窗弹出时会出现偶现页面闪烁;
- 仅能处理静态样式表,对于组件库 JS 动态生成的内联样式、运行时拼接出来的选择器完全无能为力。
strictStyleIsolation:直接把子应用塞进 Shadow DOM
隔离最彻底,但代价是兼容性:
:root上的变量读不到;- 第三方库依赖
document.querySelector找节点,直接失灵; - 弹层层级、字体、资源相对路径全要单独救;
- 官方把它标成 experimental,生产环境不敢用。
所以只能自己做
官方的两个字段本质都是在运行时改 CSS 选择器,它能保证"不污染别人",但保证不了"自己不被别人影响",也处理不了组件库写死的类名和根节点级别的变量。
我们的做法换了个层面:在构建期改本应用自己的产物。作用范围被严格限制在本应用的 CSS 和 JS 里,不碰运行时,不碰别的应用,也就不需要去猜别人写了什么。
二、我们项目里的三种情况
落地下来不是一套方案,而是三套,分别对应我们遇到的三种问题,踩到的三种坑。
情况一:多个系统都在用 antd
现象:大家针对于自己的系统特性,都对ant-design进行了适合自己项目的样式调整。所以就导致了ant-* 类名互相覆盖,按钮、表单、弹窗样式时不时变形,样式变成了其他系统的样式。
为什么官方方案解决不了:experimentalStyleIsolation 能加前缀,但加完 :root 类规则又失效了,等于把主题打坏,还有就是好多项目都已经是非常成熟的系统,代码体量很大,如果所有样式都使用prefix去修改代码中的样式的话,那么需要修改的范围就很多,改动量很大,回归测试的时间久,风险高。
我们的做法:运行时 ConfigProvider prefixCls='sub-a' 换掉类名前缀,构建期用 loader 把静态 CSS、JS 字符串里的 .ant-* 一起改掉。
完整实现和踩坑的地方见第二篇。
情况二:多个系统都在用 AG-Grid
现象:表格行高被压扁、边框消失、右键菜单和筛选面板样式错乱。
为什么官方方案解决不了:AG-Grid 的类名写死在样式文件里,改前缀等于把它的主题变量机制一起拆了;而官方那套前缀改写只能作用在样式表层。
我们的做法:DOM 保留 .ag-* 原样,构建期用 loader 给每条选择器补一个祖先作用域 .sub-a-aggrid-scope,样式只在带这个类的容器里生效。
完整实现和遇到的坑见第三篇。
情况三:多个系统都有自己的主题
现象:A 切暗色,B 跟着变黑;:root 里声明的 --color-* 互相串味。
为什么官方方案解决不了:这一条跟组件库完全无关,抢的是同一个 <html>。documentElement.setAttribute('data-theme', ...) 谁写谁生效,官方字段管不到别人往根节点写东西。
我们的做法:主题标记从 <html> 挪到本应用根容器 #sub-a-root,所有 :root 改写成 #sub-a-root,弹层挂载点一起迁进容器。
完整实现和 遇到坑见第四篇。
三种情况的共同点:都是"多个应用共用同一份全局资源"——共用一套类名、共用一套选择器锚点、共用一个根节点。
三、遇到别的共用插件,方法是一样的
这套思路不挑组件库,换成别的插件也能套:
- 插件支持改前缀 → 走情况一:运行时换名字 + 构建期改写静态资源。Element Plus、Vant 这类都有 namespace / prefixCls 配置;
- 插件不支持改前缀 → 走情况二:DOM 不动,构建期给选择器加祖先作用域;
- 插件往
<html>/body写全局状态或变量 → 走情况三:把状态挪到自己的容器,挂载点跟着迁。
唯一要注意的是:选择器改写规则不能照搬。AG-Grid 那套 loader 依赖它的主题复合选择器写法,直接套到 .el-*、.van-* 会出错,得重新验证一遍改写结果。
四、按需取用,不用三套全改
这三篇是并列关系,不是流水线。自己的项目自己最清楚哪里有问题:
- 只踩了 antd 的问题,就只做第二篇那件事;
- 只有 AG-Grid 打架,就只做第三篇;
- 只有主题串味,就只做第四篇;
- 三个都踩,才需要三套一起上。
三套互不冲突,因为它们改的位置不一样:一个改运行时类名,一个改选择器结构,一个改根节点和 :root。
五、三套方案共同的底线
- 构建期只能处理静态文本。JS 运行时拼出来的类名(
'ant-' + name)、运行时 inject 的 CSS,loader 一律拦不到,这类场景必须业务侧兜底; - 浮层是最容易漏的地方。antd 弹窗、AG-Grid 菜单、主题变量默认都面向
body,挂载点不迁,等于没做; - 升级要回归。组件库、主题包升大版本后,很可能引入新的选择器写法,让改写规则失效,必须重跑校验脚本;
- 隔离要可验证。每套方案都配一段产物校验脚本,把"有没有残留"变成数字,别靠肉眼。
系列文章
- 第二篇:Ant Design 5 在 qiankun 下的类名前缀重命名隔离
- 第三篇:AG-Grid 在 qiankun 下的 CSS 命名空间隔离
- 第四篇:qiankun 主题隔离,把 data-theme 从 html 挪进自己的容器
哪篇对应你的问题,直接翻哪篇。