把一个运行多年的jQuery老工程接入qiankun微前端架构时，最常见的翻车现场就是：子应用加载后，主应用的页面突然多了奇怪的全局函数，或者主应用里定义的$.ajax行为被改得面目全非。这类问题的根源在于沙箱机制对jQuery这类“重度依赖window”的库的拦截能力是有限的。本文将系统剖析qiankun和single-spa体系下JS沙箱的工作原理，梳理jQuery造成全局变量污染的几条典型路径，并给出可直接落地的改造方案。
一、qiankun沙箱的底层原理：Proxy如何拦截全局读写
qiankun的核心能力之一是JS沙箱，它通过Proxy对window对象做代理，把子应用对全局作用域的所有读写操作重定向到一个隔离的fakeWindow上。理解这个机制是解决污染问题的前提。
qiankun内置了三种沙箱模式：LegacySandbox（单实例下的代理沙箱）、ProxySandbox（多实例下的不污染代理沙箱）和SnapshotSandbox（不支持Proxy的浏览器如IE下的快照沙箱）。其中ProxySandbox的实现思路是：创建一个空对象fakeWindow，然后用Proxy的get和set陷阱拦截访问。读属性时优先从fakeWindow取，取不到再从原生window取；写属性时只写入fakeWindow，不触碰真实的window。这样一来，子应用往全局挂载的所有变量都被困在fakeWindow里，卸载时直接丢弃fakeWindow即可，主应用毫发无伤。
// ProxySandbox的简化原理
class ProxySandbox {
constructor() {
this.fakeWindow = {};
this.proxy = new Proxy(window, {
get(target, key) {
// 优先从fakeWindow读取
if (key in this.fakeWindow) return this.fakeWindow[key];
// 部分属性需要绑定到原生window，如alert、location
const value = target[key];
return typeof value === 'function' && !value.prototype ? value.bind(target) : value;
},
set(target, key, value) {
// 只写入fakeWindow，不污染真实window
this.fakeWindow[key] = value;
return true;
}
});
}
}但要注意，沙箱只能拦截“经过Proxy”的访问。子应用的代码是被qiankun改写后执行的——qiankun会通过with语句把代码包一层，使其中的自由变量解析时指向proxy而不是真实的全局对象。如果代码以某种方式拿到了真实的window引用（比如通过window.window的边缘case、iframe的contentWindow、或Function('return window')()这类动态构造），沙箱就形同虚设。jQuery恰恰有很多这样的“逃逸”路径。
二、jQuery污染全局变量的四条典型路径
jQuery是一个诞生于2006年的库，它的设计假设是“独占整个页面”。接入微前端后，这种假设会从多个方向击穿沙箱防线。
第一是静态资源加载路径。qiankun默认对子应用的HTML做处理，其中内联的script会被提取出来在沙箱中执行，但通过<script src="jquery.js">外链引入的脚本，默认不会经过沙箱包装。如果jQuery是通过原生script标签加载的，它拿到的是真实的window，直接把$和jQuery挂到了真实全局上，与主应用的jQuery（如果主应用也用）立刻产生版本冲突，这正是经典的jQuery.noConflict()要解决的场景。
第二是DOM共享带来的污染。沙箱只隔离JS变量，不隔离DOM。jQuery会把expando属性（形如jQuery351023...的随机key）挂到操作的DOM节点上，用于存储内部数据缓存。子应用和主应用操作同一个document下的节点时，事件队列$._data(element, 'events')也挂在共享DOM上，双方绑定的事件会互相干扰，卸载子应用时事件也不会自动清理，造成内存泄漏。
第三是插件系统的全局副作用。大量jQuery插件（如老的easyui、layer等）会往window上挂全局函数、往document上绑定全局事件（resize、scroll、keydown），甚至直接改写$.fn的原型。这些操作要么发生在沙箱外，要么绑在了共享的document上，都是沙箱管不到的地方。
第四是快照沙箱的固有缺陷。如果项目必须兼容IE，只能降级到SnapshotSandbox，它的工作方式是激活前快照window、卸载后逐项恢复。这种沙箱只支持单实例运行，且如果子应用通过异步回调在卸载后又写入全局变量，恢复机制就错过了，污染照样发生。
三、实战解决方案：让jQuery安全地待在沙箱里
针对上述路径，改造工作可以分成资源加载、全局清理、DOM隔离三个层面来做。
首先是资源加载层面。推荐的做法是去掉外链script，把jQuery改为在子应用入口手动import，让webpack把它打进bundle。这样qiankun执行bundle时代码处于with(proxy)作用域内，jQuery内部的window.$ = jQuery赋值会被Proxy拦截，写入fakeWindow而不是真实window。如果jQuery必须以外部脚本方式加载，可以在主应用加载子应用时配置runScript或使用qiankun提供的loader钩子把脚本内容取回后交给沙箱执行：
// 子应用注册时配置，确保外链脚本也走沙箱
import { registerMicroApps, start } from 'qiankun';
registerMicroApps([
{
name: 'legacy-jquery-app',
entry: '//localhost:7100',
container: '#subapp-container',
activeRule: '/legacy',
props: {
// 通过props告知子应用挂载容器，避免直接操作body
mountContainer: '#subapp-container'
}
}
], {
// fetch自定义：把外部jquery.js的内容取回，由qiankun沙箱统一执行
fetch: async (url) => {
const res = await window.fetch(url);
return res;
}
});
start({ sandbox: { experimentalStyleIsolation: true } });其次是全局挂载的冲突处理。如果主应用和子应用都需要jQuery且版本不同，必须在子应用入口调用$.noConflict(true)，把$和jQuery两个全局名都交还给之前的使用者，然后通过模块作用域持有引用：
// 子应用入口 import jQuery from 'jquery'; const $ = jQuery.noConflict(true); // 后续统一使用模块内的$，不再依赖全局 export default $;
第三是DOM与事件层面的隔离。子应用应该只在自己的容器内操作DOM，把选择器限定在props.mountContainer范围内，避免$(document)、$('body')这类全局选择。对于必须绑定的document级事件（如点击外部关闭弹层），要在unmount生命周期里手动解绑：
export async function mount(props) {
render(props);
// 记录document级事件，便于卸载时清理
props.docHandlers = {
click: () => closeAllPopups($)
};
$(document).on('click', props.docHandlers.click);
}
export async function unmount(props) {
$(document).off('click', props.docHandlers.click);
// 清空jQuery内部缓存，移除expando残留
$('*').removeData();
$('#subapp-root').empty();
}最后是样式与CSS隔离。qiankun的experimentalStyleIsolation会给子应用样式加作用域前缀（类似shadow-DOM的scoped方案），但老jQuery项目大量内联样式和JS动态设置样式的操作是拦不住的，这类情况建议逐步迁移到CSS Modules或在容器上加命名空间class。此外，如果条件允许，把老jQuery应用包一层iframe再嵌入微前端，虽然牺牲了通信便利性，但能获得浏览器级别的完整隔离，是存量系统改造成本最低的兜底方案。
四、single-spa场景的差异与补充策略
single-spa本身不提供沙箱，它只负责生命周期编排。因此如果直接用single-spa接jQuery应用，全局污染问题会比qiankun更严重，需要自己引入systemjs或配合qiankun的沙箱能力。常见做法有两种：一是用single-spa的Parcel模式包装老应用，配合import-map管理依赖；二是在老应用外面包一层自研的Proxy沙箱，思路与ProxySandbox一致，但要额外处理老代码中的this指向和严格模式兼容问题。
还有一种工程化手段值得考虑：对无法修改的老代码，可以在构建期用babel插件或字符替换的方式，把代码中的window引用统一改写为__SUB_APP_WINDOW__这类注入的代理变量，从编译层面杜绝逃逸。这种方案侵入性强但效果彻底，适合代码量大、又不敢轻易动运行时逻辑的存量工程。
总结来看，jQuery与微前端沙箱的冲突本质是“独占式库”与“共享运行时”的架构矛盾。qiankun的Proxy沙箱能解决大部分JS变量污染，但DOM共享、外部脚本、document级事件这三块必须靠工程手段手工兜底。改造时建议按“入口改造优先、noConflict兜底、事件显式清理、必要时iframe兜底”的顺序推进，就能让老应用平稳地融入微前端体系。
qiankun沙箱微前端jQuery全局变量污染修改时间：2026-08-31 08:57:11