qiankun v3 样式隔离内部实现解析scope、blob-link 与 CSSOM 拦截机制【免费下载链接】qiankun Blazing fast, simple and complete solution for micro frontends.项目地址: https://gitcode.com/gh_mirrors/qi/qiankun本文面向 qiankun 维护者与进阶使用者系统拆解 v3 中样式隔离sandbox.styleIsolation的完整实现管线它如何基于原生 CSSscope对行内style、外部link relstylesheet与运行时 CSSOM 注入三条路径分别改写样式以及由此带来的缓存策略、preload 重写与边界限制。读完本文你将理解为什么 v3 弃用 2.x 的 Shadow DOM 方案、何时可以安全启用该选项以及排查启用后应用失样式问题的完整思路。面向使用者的能力边界与开启方式见 样式隔离概念一步步开启指南见 启用 CSS 样式隔离。样式隔离的目标是阻止微应用的 CSS 泄漏到主应用或其兄弟应用中。在 qiankun v3 中这是一个可选开启、按应用粒度生效的运行时机制其实现建立在浏览器原生 CSSscope规则之上——而不是 Shadow DOM。开启后微应用携带的每一份样式表都会被改写使其中规则只在该应用容器内部命中。机制全貌什么是它、什么不是它在应用的配置中设置sandbox: { styleIsolation: true }qiankun 就会把该应用的 CSS 包装进一个绑定到应用容器的scope块scope ([data-nameyour-app]) { /* 该应用的规则已被改写 */ }作用域根scope root恒定为[data-nameappName]。qiankun 会给每个应用容器打上与注册应用名相等的data-name属性并据此推导选择器。这一行为不可自定义——没有选项允许传入你自己的 scope root。容器属性打标的实现位于 packages/sandbox/src/core/sandbox/container.ts挂载时写入container.dataset.name appName卸载时若不存在其他同名实例则恢复原属性或移除从而保证data-name与应用生命周期严格同步。由于包装发生在 CSS 层面而非将应用挂载进 shadow tree微应用的 DOM 仍然留在主文档中全局库、portal、document级查询都按 JS 沙箱 预期的方式继续工作。隔离在意图上是单向的它阻止微应用声明的规则作用到容器之外但不会沙箱化主应用或浏览器默认样式表对微应用内部的影响。完整分支流程如下样式隔离默认关闭。如果你从不设置sandbox.styleIsolationstyle与link节点会原样穿过 loader不做任何处理。v3 与 2.x 的本质差异v3 的样式隔离就是上文这套scope blob-link 机制由一个布尔开关控制。2.x 的sandbox.strictStyleIsolation与sandbox.experimentalStyleIsolation基于 Shadow DOM在 v3 中不存在唯一的旋钮是sandbox.styleIsolation。从 2.x 迁移的细节见 从 qiankun 2.x 迁移。路径一行内style的重写管线对于行内style元素qiankun 读取其textContent进行变换再把作用域化结果写回同一节点。除包裹scope之外变换还做了几件单纯包装会做错的事。核心实现位于 packages/shared/src/assets-transpilers/style.tsfont-face与namespace被提升hoist出scope块并保持全局。作用域化font-face会破坏字体加载namespace必须是文档级的。源码用extractAtRules先把这两类规则抽取出来最后再拼回作用域块之前见transpileStyleTextSync。keyframes以每应用前缀重命名——格式为__qk_appName_name——并且所有animation/animation-name引用都会同步改写。这是因为scope只作用域化选择器不会作用域化全局的 keyframe 命名空间两个都定义了spinkeyframe 的应用若不重命名会互相覆盖。源码中prefixKeyframes用QIANKUN_KEYFRAMES_PREFIX __qk_拼接前缀并同时重写animation-name长属性与animation简写属性对animation-*长属性有守卫避免误伤见 style.ts。行内样式的相对url(...)不做 rebase。当前行内路径不会向 transformer 传入样式表 base URL。当宿主与微应用不共享同一 document base 时请使用绝对、data:或blob:URL。import被递归内联。每个被导入的样式表都通过应用装饰后的fetch获取、执行同样变换后拼接进来并用 visited 集合去重重复导入会告警并跳过。由于该路径不基于微应用 entry 解析相对地址行内样式中请使用绝对 import URL。递归内联与相对路径解析实现在inlineImports中style.ts。因为内联import可能产生网络往返qiankun 会先同步清空style的textContent待所有内容解析完成后才填入作用域化 CSS见 style.ts。这避免了在 fetch 窗口期未作用域的源样式全局生效。路径二外部link relstylesheet的 blob-link 方案原生scope只能包装你掌控的 CSS 文本而浏览器对外部样式表是不透明加载的——没有钩子可以在其到达时包装它。因此开启样式隔离后qiankun 会阻止浏览器原生加载link自己接管 fetch即代码库所称的blob-link 方案实现在 packages/shared/src/assets-transpilers/link.ts将href基于 base URL 解析然后移除href属性并把原始地址存入data-href。没有href浏览器永远不会加载未作用域的样式表。通过应用装饰后的fetch获取 CSS再对它执行与行内样式相同的scope包装变换。在同一link元素上以blob:URL 提供服务包装后的 CSS 成为Blob其 object URL 被重新设回元素的href。与行内路径不同外部样式表的变换会收到解析后的样式表 URL 作为 base。因此相对url(...)和import引用都会先基于外部样式表 URL 解析再应用作用域化。节点身份是被刻意保留的——qiankun 只交换href从不替换元素。这让所有原生link语义免费保持有效media、disabled、title以及document.styleSheets中的条目始终存活流式 loader 的pending 样式表阻塞后续脚本簿记仍能看到一个正常的 pending linkblob href 落地时触发load应用附加在动态注入link上的onload/onerror处理器也继续工作。如果 fetch 或变换失败blobhref 永远不会被设置——元素自身不会发出任何事件。qiankun 会在该 link 上手动派发error事件并丢弃样式表见 link.ts而不是回退为未作用域加载。丢弃是刻意选择无法被作用域化的样式表不允许全局泄漏。缓存与去重变换后的样式表先按 URL 缓存再按应用作用域键appName:scopeRoot缓存同一 URL 的并发 fetch 会被去重pendingFetches共享同一个 Promise。因此被多个应用共享的同一外部样式表只会按不同 scope root 的数量各 fetch 与变换一次。link.ts还暴露了clearStylesheetCache()与getStylesheetCacheStats()用于测试与监控link.ts。路径三运行时 CSSOM 的 insertRule 拦截运行时以编程方式插入的样式从不经过 loader所以 qiankun 在 CSSOM 层拦截它们。当样式隔离激活时CSSStyleSheet.prototype.insertRule被 monkey-patch引用计数只要存在存活的样式隔离应用就安装最后一个卸载时才移除见 packages/sandbox/src/patchers/dynamicAppend/forStandardSandbox.ts。若样式表拥有节点ownerNode携带样式隔离配置传入的规则文本在到达原生insertRule前会被作用域化——包裹scope并做同样的 keyframe 重命名。transpileStyleRule的同步实现见 style.ts。这条同步路径会跳过已scope包裹的规则避免重建时双重包裹并保持font-face/namespace全局与静态变换保持一致。这正是 CSS-in-JS 库与运行时构建样式表的框架能够与其他样式一并被作用域化的原因。patchCSSOM在卸载时还保留宿主在 qiankun 初始化后自行安装的补丁仅在当前补丁仍是被安装的那个时才恢复原生实现。Preload 重写让预热请求不被浪费通过link relpreload asstyle预热的响应只能被原生样式表请求复用。开启样式隔离后transpiler 通过fetch()消费样式表原始 preload 将白费。因此 qiankun 会把该 link 改写为asfetch并加上crossoriginanonymous除非它已使用use-credentials使随后的fetch()能复用预热响应。该逻辑位于 link.ts注释明确说明其与 script/modulepreload 改写同一 rationale保持 preload 缓存可命中。另外只要 ESM 沙箱 处于激活状态qiankun 就会把relmodulepreload改写为relpreload asfetch因为引擎导入的是改写后的 blob URL 而非原始模块 URL。此改写不依赖样式隔离原始 modulepreload 的凭据行为通过crossorigin设置保留link.ts。需求与限制::: warning 需要浏览器原生支持 CSSscope实现中没有任何 polyfill 与回退方案完全依赖浏览器支持 CSSscope规则。在不支持scope的浏览器中包裹规则是惰性的样式不会被隔离。scope是浏览器较新引入的特性依赖它之前请对照你的目标浏览器矩阵验证支持情况。 :::::: warning 外部样式表必须可被 CORS 获取 因为外部样式表通过fetch重新获取并以blob:URL 提供跨域样式表必须返回正确的 CORS 头。若无法获取qiankun 会丢弃它——样式表静默消失伴随一条 console 警告而不是以未作用域状态加载。请为微应用样式表开启 CORS否则隔离应用会以无样式状态渲染。 :::::: info 已知边界场景font-face冲突字体规则被刻意保持全局以保证字体正确加载。两个声明相同font-family名称的应用因此可能冲突。请为每个应用使用不同的 font-family 名称。动态拼接的 keyframe 名称keyframe 重命名是静态文本变换。如果 JS 在运行时用字符串拼接构造动画名称而不是在 CSS 中字面书写该引用不会被改写动画可能无法解析。 :::::: tip 与 qiankun 2.x 的差异 v3 样式隔离就是本文描述的scope blob-link 机制由一个布尔值切换。2.x 的sandbox.strictStyleIsolation与sandbox.experimentalStyleIsolation基于 Shadow DOM在 v3 中不存在唯一旋钮是sandbox.styleIsolation。迁移参考 从 qiankun 2.x 迁移。 :::容器外的内容不在作用域内菜单、对话框、tooltip 等渲染到document.body下而非微应用容器内的 portal位于 scope root 之外应用的作用域选择器不会命中它们。建议将 portal root 放在props.container内或显式样式化该外部表面。作用域按应用名name而不是实例句柄键控复用同一name的并发实例共享同一作用域选择器当它们的 CSS 需要彼此隔离时请使用不同的名称。完整用户侧能力说明见 样式隔离概念。公共开关sandbox.styleIsolation选项类型默认值说明sandbox.styleIsolationbooleanfalse通过scope包裹启用运行时 CSS 隔离。启用后微应用的所有样式都被作用域化到其容器[data-nameappName]。styleIsolation是应用配置中sandbox对象内的按应用字段。配置的解析发生在 packages/qiankun/src/core/loadApp.tstypeof sandboxCfg object ? { enabled: true, styleIsolation: Boolean(sandboxCfg.styleIsolation) } : sandboxCfg随后作为styleIsolation透传给 sandbox 控制器与 node transformerloadApp.ts。将它与styleIsolation作用域根生成逻辑container.tsscopeRoot: \[data-name${appName}]对照阅读可以完整看到从配置项到最终scope 选择器的全链路。作为loadMicroApp的第二个参数传入import { loadMicroApp } from qiankun; const container document.getElementById(subapp-viewport); if (!container) throw new Error(subapp-viewport not found); const microApp loadMicroApp( { name: react-app, entry: //localhost:7101, container, }, { sandbox: { styleIsolation: true }, }, );启用与验证从开关到确认生效在路由驱动模式下把配置放入应用注册对象的configuration字段React 与 Vue 的MicroApp组件则通过settingsprop 传入相同配置见 启用 CSS 样式隔离。启用后建议按以下步骤验证在宿主与微应用中添加同 class 的测试元素在微应用 CSS 中给该 class 一个明显的样式确认只有微应用容器内的元素获得该样式卸载应用并确认其容器与动态插入的样式被清理。若启用后应用变成无样式状态优先排查两件事浏览器是否支持scope以及 CORS 是否拦截了某个外部 CSS 请求。资源加载失败的捕获方式见 处理加载与运行时错误。完整配置字段列表见 AppConfigurationloadMicroApp的完整签名见 loadMicroApp。【免费下载链接】qiankun Blazing fast, simple and complete solution for micro frontends.项目地址: https://gitcode.com/gh_mirrors/qi/qiankun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考