1. 一次白屏事故逼我重新思考资源加载机制去年我们内部运营后台触发过一起不算大但足够揪心的线上事故大促数据看板在流量高峰期突然白屏运营同学截了一整屏的报错图发到群里。排查到最后根因非常朴素——页面运行时动态插入的六七个脚本里有一个来自公共CDN的脚本超时了而这个脚本又被后面的模块依赖后续初始化逻辑直接中断整个应用就瘫了。更让人难受的是这种问题在架构上几乎无解。我们的运营后台不是单一SPA而是混合了webpack模块、历史遗留的jQuery插件、第三方报表SDK等多种技术栈。这些资源很多是在页面运行过程中按需加载的之前一直是谁的模块谁管append一个script标签就不管了的状态。那次事故之后我意识到动态资源加载这件事在业务侧的价值被远远低估了——它不只是把文件拉下来而是涉及顺序保证、并发控制、失败恢复、缓存命中等一系列工程问题。我花了大概两周时间把这些零散诉求收敛成一个专门的加载调度器起名iloader。它本质上是一个零依赖、面向浏览器环境的JavaScript资源加载管理器负责统一处理脚本、样式、图片三类资源的动态加载核心能力包括依赖顺序调度、并发上限控制、超时重试、CDN降级和内存缓存。这篇文章把我从设计到上线的完整思考过程写下来包括踩过的坑和最终采用的方案希望对同样被动态资源折磨过的同学有帮助。2. 动态加载脚本这事为什么必须有个专门的调度器2.1 原生script标签的真实不可控性可能有人会觉得动态加载脚本不就是document.createElement(script)然后append到head里吗非要搞个加载器是不是小题大做。我理解这种想法因为我以前也这么干。但当你认真把原生方案逼到极限的时候会发现它有非常具体的问题。第一个问题是失败无感。原生script标签的onerror事件虽然大部分浏览器支持但它在某些场景下压根不触发。比如Safari在无网环境下创建script标签有时只会走超时连onerror都没有。你说我监听load事件不就完了但load的成功定义也有歧义——脚本下载了HTTP 200不一定等于执行成功脚本语法错误会导致onload后页面直接报ReferenceError你的Promise已经resolve了但业务代码根本没跑起来。第二个问题是并发和顺序的冲突。场景是这样的页面要加载A、B、C三个脚本C依赖BB依赖A。如果用原生的方式依次append三个tag浏览器不一定按你append的顺序执行。async属性会让脚本下载完后立刻执行顺序完全随网络波动即便不设置async动态创建的script默认虽然是阻塞式的但如果你在某个阶段混合了动态插入和已缓存脚本执行时机照样乱。你只能靠回调地狱一层一层嵌套或者自己维护一个队列很快代码就变成面条。第三个问题是超时无人管。原生加载没有超时概念如果一个CDN域名被网络策略阻断TCP连接长时间挂起页面就一直白。这个场景我在真实环境中遇见过不止一次每次都要人工刷新或者等较长的时间超时。第四个问题是重复加载以谁为准。业务模块A加载了jQuery 1.x模块B又加载一遍jQuery 2.x两个版本共存导致插件行为异常。原生机制根本不关心你是不是已经加载过某个src加载过的脚本能否重复执行完全交给浏览器缓存但缓存也有命不中的时候命不中就会二次执行对某些带全局副作用的脚本就是一场灾难。2.2 现有方案的覆盖盲区市面上不是没有处理动态加载的库比如当年很流行的script.js、loadjs但它们解决的问题普遍比较单一就是加载脚本并通知完成没有把并发控制、优先级、依赖DAG、超时重试、缓存去重这些真正影响生产环境稳定性的能力整合起来。你可以用多个库拼装但拼接出来的边界责任很难说清。webpack的动态import是另一个思路它把资源换成chunk通过运行时runtime来加载体验统一但它适合构建期已知模块边界的场景。像我们这种半遗留系统很多脚本的地址是在运行时根据用户权限动态拼出来的有些还是其他团队维护的跨域静态资源跟构建链路完全没关系。这种情况下需要一个运行时级别的加载器而不是构建工具内部的机制。2.3 iloader解决的核心问题清单我在设计之前先列了一个问题清单后面所有API和实现都围绕这张单子展开资源加载的成功/失败有统一可感知的结果并支持超时判定。可以声明依赖关系加载器负责拓扑排序保证执行顺序。可以控制并发上限避免同时创建几十个网络请求把页面带宽打满。支持优先级让首屏关键资源先加载非关键模块让路。支持失败重试且重试策略有序、可配置不能无限重试也不能重试太急。支持CDN降级主资源失败自动切换备用地址。对重复加载有精确的缓存判断不重复请求、不重复执行。对宿主环境保持零依赖直接script标签引入或者ESM引入都可以跑。这几个问题如果都解决了动态加载这一步的基础设施就算立住了。3. iloader核心API设计按使用场景组织接口3.1 三类资源的统一加载接口iloader对外暴露的核心API不复杂。脚本、样式、图片三种资源类型各一个方法加上一个通用批量load入口基本就覆盖了95%的使用场景。import { loadScript, loadStyle, loadImage, load } from iloader; // 加载单个脚本 const script await loadScript(https://cdn.example.com/lib/sdk.js, { timeout: 10000, fingerprint: 20240115 }); // 加载样式 await loadStyle(https://cdn.example.com/styles/theme.css); // 加载图片 await loadImage(https://img.example.com/banner.png, { crossOrigin: anonymous }); // 批量加载支持依赖和并发控制 await load({ resources: [ { type: script, src: a.js, id: a }, { type: script, src: b.js, id: b, deps: [a] }, { type: script, src: c.js, id: c, deps: [b] }, ], concurrency: 2, timeout: 15000 });API的粒度我刻意控制得很薄。loadScript负责单资源load负责组合编排。这样单个资源逻辑容易测试组合逻辑也容易理解。3.2 为什么坚持Promise而不是回调我在第一版其实用的是回调风格类似loadScript(src, { onSuccess, onError })。用了一周就推翻了原因很现实回调难以组合。当我需要两个脚本都加载完成后再初始化回调就得额外写一个计数器当我要处理脚本A失败但脚本B还要继续回调的错误分发就变得很绕。Promise带来两个直接收益一是可以用async/await写线性逻辑出错直接用try/catch捕获二是Promise天然支持all、race等组合方式比如置资源加载和整体超时赛跑代码非常直观。try { await load({ resources: [...] }); initApp(); } catch (err) { console.error(关键资源加载失败进入降级页面, err); renderFallback(); }3.3 参数设计里的细节考量关于选项参数有几个细节我觉得很值得说明。timeout默认值我设在15000ms。这个值不是拍脑袋定的。实测下来常规CDN在弱网环境下一个几十KB的JS文件从发起到执行完毕一般不会超过8秒超过15秒大概率是网络链路出问题等待没有意义。如果你有更大的离线包或者超大资源可以在单次调用里覆盖。fingerprint参数是给资源URL加版本指纹用的。很多团队的静态资源发布不一定会改写文件名但内容变了之后如果继续用旧URL浏览器缓存会把你坑哭。iloader把指纹拼到查询参数上便于业务方按版本号刷新缓存。crossOrigin参数用于图片加载。如果业务里要用canvas处理图片但不希望污染画布这个参数应该传anonymous。类似的还有script标签的crossorigin属性尤其在需要捕获跨域脚本错误时很有用这个后面讲错误处理时还会再提。4. 并发控制、优先级与依赖调度的实现细节4.1 用信号量实现并发上限先问一个问题为什么动态加载还需要并发控制浏览器对同一域名的TCP连接数本来就有上限看起来不需要应用层操心。但真实业务里资源经常是分散在多个域名下的加上HTTP/2多路复用之后同一连接可以承载大量并发请求。如果我们一次性把20个脚本同时扔给网络层个别超大脚本会抢占带宽导致首屏关键的另外两个小脚本迟迟回不来。所以并发控制的意义不是绕过浏览器限制而是给不同优先级的资源合理地分配网络窗口。iloader内部用一个很简单的信号量Semaphore实现并发上限。核心逻辑只有两个方法acquire和release。class Semaphore { constructor(max) { this.max max; this.current 0; this.queue []; } acquire() { return new Promise(resolve { if (this.current this.max) { this.current 1; resolve(); return; } this.queue.push(resolve); }); } release() { this.current - 1; const next this.queue.shift(); if (next) { this.current 1; next(); } } }使用起来就是每个加载任务先await semaphore.acquire()拿到通行证再发起网络请求最后在finally里release。信号量的妙处在于它不只是排队而是允许任务带着各自的状态进入等待区谁先让位谁先上和任务的执行上下文完全解耦。4.2 并发数默认值为什么是6iloader默认并发数是6。这个数主要是基于对浏览器HTTP/1.1时代连接限制的延续性习惯以及移动端弱网场景的保守考虑。HTTP/2时代虽然并发能力大幅提升但移动端设备的内存和CPU有限响应式渲染过程中如果同时解析执行大量JS主线程卡顿非常明显。经过我们后台实际场景的对比测试并发数为6时整批20个脚本的总耗时和使用12并发几乎持平但首屏可交互时间TTI反而更短因为关键资源不会被后排资源拖累。如果你的场景中大量资源是独立的、非关键的可以适当调高到8或10。4.3 优先级调度的实现思路有些资源加载器不做优先级只靠调用方手动控制顺序。但我们的业务场景里资源是不同团队异步注册的。比如用户点开一个报表页面最优先的其实是权限校验脚本其次才是图表SDK而埋点统计脚本可以放到最后。如果不做优先级回调注册早的脚本会先占坑关键资源反而可能排后面。iloader在调度队列里给每个任务维护一个priority字段数字越小优先级越高。信号量发放窗口时不是简单FIFO而是从队列里找出当前最高优先级的等待任务放行。还是上面那个队列例子只不过acquire返回的任务列表需要按优先级排序。这里我没直接改动信号量而是在调用层维护了一个优先队列当某个任务release时把队首优先级最高的waiting resolve掉。这样信号量的语义保持简单优先级逻辑是叠加在上面的。class PriorityQueue { constructor() { this.items []; } enqueue(task) { this.items.push(task); this.items.sort((a, b) a.priority - b.priority); } dequeue() { return this.items.shift(); } }这样设计后一个资源如果声明了priority: 0那么它会插队到所有默认优先级比如10之前。实际使用中我把权限与鉴权资源设为0首屏渲染相关的框架脚本设为2图表类SDK设为5埋点和非关键分析脚本设为10。4.4 依赖DAG的拓扑排序依赖关系是资源加载里最挠头的一块。iloader要求每个资源可以声明deps数组里面填的是它所依赖的资源id。在load入口处所有资源会先被构造成一个DAG有向无环图然后做拓扑排序确保任何资源都在它的依赖项之后开始加载。加载过程则是一个动态调度过程每当有资源完成就去推动依赖它的下游资源进入就绪状态。一个关键实现原则是依赖关系并不等于加载顺序的严格串行。A和B互不依赖它们可以并发加载B依赖A则B要等A结束后才能进入信号量队列。这样整个图只多出依赖边带来的等待时间而不是简单地把所有资源排成一条线避免无谓的串行化。为此我在解析阶段会给每个节点打上入度计数当一个依赖完成就把它下游节点的入度减一入度归零才放入ready队列参与并发调度。这个流程写出来不算复杂但拓扑排序的数据结构细节很容易出错。我调试时踩过一个典型的坑如果资源声明了循环依赖A依赖BB又依赖A拓扑排序会死循环。所以在解析阶段我专门做了环检测一旦发现环就抛出结构化错误并且把环上的节点id直接报出来方便排查。5. 错误重试和降级策略让加载器成为可用性问题的最后防线5.1 怎么可靠地判定一次加载失败判定失败这件事比听起来复杂。真实网络环境下加载失败大体有三种形态网络错误导致onerror触发、长时间无响应需要超时判定、以及HTTP 4xx/5xx状态码在跨域场景下拿不到详情。第一和第三种可以通过监听script标签的error事件感知但第二种必须靠定时器兜底。在iloader里每个加载任务用一个settled标志位来保证resolve/reject只发生一次。function loadScript(src, options) { return new Promise((resolve, reject) { const script document.createElement(script); script.src src; script.async true; let settled false; const timeout options.timeout || 15000; const timer setTimeout(() { if (!settled) { settled true; reject(new Error(iloader: script load timeout - ${src})); cleanup(); } }, timeout); function onSuccess() { if (settled) return; settled true; clearTimeout(timer); resolve({ src, tag: script }); cleanup(); } function onError() { if (settled) return; settled true; clearTimeout(timer); reject(new Error(iloader: script load error - ${src})); cleanup(); } function cleanup() { script.onload null; script.onerror null; } script.onload onSuccess; script.onerror onError; document.head.appendChild(script); }); }这里有个平时没人提的细节事件处理完之后一定要重置onload/onerror。因为script标签一旦加载完成且不再被引用浏览器在垃圾回收前仍然可能触发第二次事件挂了清理函数能避免重复回调带来的诡异表现。这个坑我在早期版本遇到过一个脚本由于某种原因被重复执行了两次排查了很久才发现是事件回调没有拆干净。关于跨域脚本的错误详情如果脚本通过script标签加载浏览器的onerror事件拿不到HTTP状态码只能知道失败这个事实。如果你需要状态码级别的详细日志可以给script标签加crossoriginanonymous并且要求脚本服务器响应头带上Access-Control-Allow-Origin头。代价是如果服务器没返回CORS头错误捕获反而会失效所以这功能做成配置项默认不开。5.2 指数退避重试的参数与实现重试策略我选了指数退避加随机抖动。基本公式是delay min(baseDelay * 2^attempt, maxDelay)attempt从0开始。默认baseDelay是500msmaxDelay是8000ms最大重试次数为3次。为什么不是固定间隔重试因为很多资源加载失败是瞬时网络抖动等一小段时间网络就能恢复但如果是域名被断或证书问题固定间隔重试只会给服务器添堵。指数退避一方面在初期快速重试抓住瞬时恢复的机会另一方面长退避防止雪上加霜。抖动jitter更重要。如果同一时间几百个用户同时触发重试没有抖动的话所有请求会在同一个时间点打向服务器形成重试风暴。我在每次重试前对延迟做±30%的随机化有效摊平了高峰。重试循环包在资源加载函数外层async function loadScriptWithRetry(src, options) { const maxRetries options.retries ?? 3; let attempt 0; while (attempt maxRetries) { try { return await loadScript(src, options); } catch (err) { attempt 1; if (attempt maxRetries) throw err; const baseDelay options.retryBaseDelay ?? 500; const delay Math.min(baseDelay * Math.pow(2, attempt - 1), 8000); const jitter delay * (0.7 Math.random() * 0.6); await wait(jitter); } } }5.3 CDN降级和主备切换重试解决不了资源永久失效的问题。CDN域名被运营商策略误封、源站文件被误删、版本发布时文件名变更但配置没同步这些都会导致同一个地址反复失败。iloader支持在每个资源上声明fallback地址列表。await loadScript(https://cdn.example.com/lib/sdk.js, { fallbacks: [https://static-backup.example.com/lib/sdk.js, /local/vendor/sdk.js] });加载失败并重试耗尽后加载器自动尝试下一个fallback地址。如果所有备用地址都失败才会真正抛出错误。降级切换逻辑我做了个小优化一旦某个备用地址成功之后的页面会话内同src资源会优先直接使用这个成功地址不再去碰崩掉的主地址。5.4 超时和重试在并发池里的协作机制需要特别注意的是重试任务在信号量里应该被当作独立任务重新排队但比普通任务有稍高的恢复优先级。我在实践中的做法是重试任务priority在原优先级基础上临时减3让它在等待队列里稍微靠前一点。这么设计的原因是重试任务往往已经等待了一轮退避时间并发窗口如果一直被新任务抢占重试可能永远排不上。实现上加载任务对象里带一个retryCount字段每进入一次调度循环就加1重新调用acquire和execute。外层循环和信号量之间用一个generator式的执行器来串联保证每个任务无论重试几次都占用同一个并发窗口不会因为重试导致并发数虚增。这个细节很关键。如果实现不小心每个重试都新建一个信号量通行证那么3个任务重试一次就变成6个并发信号量形同虚设。我在写测试用例时专门模拟过这种重试导致并发突破的场景用来验证调度器的并发上限在任何路径下都不会超。6. 缓存设计既能去重又不吃掉浏览器HTTP缓存6.1 用Promise缓存替代简单的状态标记动态加载里有一个非常经典的问题模块A和模块B几乎同时需要加载同一个公共脚本如果加载器不够聪明就会发出两次相同的请求。最粗浅的缓存方案是维护一个已加载数组加载前先判断src在不在里面。但这个方案有个并发窗口漏洞两个任务同时进来时数组里都查不到还是会重复请求。更好的方案是直接把每个加载中的Promise缓存下来。同一个src第二次请求时直接把缓存的Promise返回这样无论多少调用方同时请求同一个资源网络层只发一次真实请求所有调用方最终共享同一个结果。const scriptCache new Map(); function loadScriptCached(src, options) { if (scriptCache.has(src)) { return scriptCache.get(src); } const promise loadScriptWithRetry(src, options).catch(err { scriptCache.delete(src); throw err; }); scriptCache.set(src, promise); return promise; }注意catch里要delete缓存。这很重要——如果加载失败还把失败Promise留在缓存里后续调用会直接拿到rejected Promise导致同样的错误永远不可恢复。失败的任务要允许下一次重新发起。6.2 缓存作用域以文档级缓存为主iloader默认的缓存作用域是当前文档生命周期也就是页面刷新后自然清空。跨页面缓存我一开始没做后来发现有些业务场景确实需要比如用户从列表页跳到详情页两个页面都依赖同一个大图表SDK如果每次进入都重新解析执行一遍体验会卡顿。为此我增加了基于sessionStorage的持久化缓存但仅针对显式声明了persist: true的资源。这个开关必须显式开启不能默认开。原因是脚本执行有副作用很多老模块在加载时会向全局暴露对象或者挂载到特定命名空间如果你在页面B里直接从sessionStorage取到已加载的标记而不重新执行脚本而页面B又恰好没有那个全局对象初始化逻辑就崩了。所以sessionStorage缓存只能用于那些确定幂等、确定不会因为重复执行出问题的资源。实际项目中这类资源占比不高大多数还是走文档级缓存就够了。6.3 如何配合HTTP缓存而不是破坏它这里有个容易混淆的地方。iloader的内存缓存和浏览器HTTP缓存的职责是不同的内存缓存管的是同一个页面上下文里不要重复加载HTTP缓存管的是同一个浏览器里不要重复下载。iloader不会拦截浏览器的HTTP请求script标签该走强缓存走强缓存该协商缓存就协商缓存。配合指纹参数使用时每次指纹变化都会生成不一样的真实URL从而绕过HTTP强缓存拿到新内容这样版本更新的语义就完全交给调用方控制。我之前见过一些加载器实现为了去重直接把script标签转换成fetchBlob URL来执行看起来能拿到body级缓存但副作用一大堆跨域CORS整不明白、source map断了、无法被浏览器开发者工具正常识别。iloader坚持只操作DOM标签加载让浏览器网络栈干它擅长的事这是稳定性的一个基本盘。6.4 缓存和并发去重的边界最后再强调一点缓存的粒度必须精确到URL配置的组合而不是简单用URL做key。实际踩过的坑是同一个脚本一个调用方要求带crossoriginanonymous另一个不要求。如果缓存key只用src后一个调用会直接复用到前一个的Promise但script标签的属性完全不同执行上下文里跨域行为就可能出现偏差。所以iloader在计算缓存key时会把src、crossOrigin、async等关键属性做序列化拼接。虽然这会让缓存命中率略微下降但换来的语义正确性完全值得。7. 实测数据与踩坑记录来自生产环境的真实反馈7.1 上线前后的量化对比测试的基准场景是我们运营后台的营销活动配置页。这个页面需要动态加载20个资源包含6个脚本、8个样式、6张图片。优化前的做法是业务代码里手动按顺序append标签超时和重试全无依赖靠人工保证。实际统计了线上两周的数据指标优化前使用iloader后页面白屏率0.6%0.08%单次加载平均失败率2.1%0.4%含成功重试后的最终失败资源加载总耗时P504.8s3.9s资源加载总耗时P9511.2s7.5s关键资源平均就绪时间3.5s2.1s白屏率下降是最直观的收益。0.6%看起来不大但运营后台的日活是大几千人在用算下来每周都有几十个用户被白屏挡住这个量级已经很影响业务。启用超时重试降级后很多偶发网络抖动造成的问题在用户无感知的情况下就被解决掉了。7.2 踩过的三个典型坑第一个坑是Safari的onload不触发。在Safari 15以下的某些版本如果动态创建的script标签来源是浏览器磁盘缓存并且页面里出现过同src标签onload事件可能不触发。表现就是脚本明明加载成功了但Promise一直挂起直到15秒超时才报错。这个坑非常隐蔽因为桌面Chrome完全复现不了。后来我做了个保护性策略在script标签加载时额外用MutationObserver监听该节点是否已插入DOM同时监听window的load事件做兜底。具体实现有点hacky但确实把Safari的挂起问题压下去了。第二个坑是超时时间设置太短误杀正常资源。我最初把默认超时设为8秒结果某次网络波动时一个4MB的离线包脚本加载了9秒直接误判超时。后来我把默认值提到15秒并且对体积超过1MB的资源做了自动的超时延长。判断体积这件事没办法提前知道我采用的近似方案是读取响应头的Content-Length如果一个脚本的声明体积大于阈值自动把timeout调成乘以1.5倍。第三个坑是关于404页面的HTML会被当作脚本执行。某些内部系统在静态资源找不到时会返回一个200状态码的HTML错误页而不是404。浏览器拿到这种响应如果Content-Type不对script标签会静默失败不触发onerror也不触发onload。这是最恶心的场景因为加载器无从感知。应对方案是提供一个validate函数在脚本执行后主动检查某个全局变量是否被正确挂载。await loadScript(legacy-lib.js, { validate: () typeof window.LegacyLib ! undefined });validate函数如果返回false当前加载会被标记为失败并进入重试流程。虽然不是所有脚本场景都能定义这么明确的全局变量但对于那些加载完必须有某个标记的旧模块这个方法几乎是救命的。7.3 监控上报与页面级自愈加载器本身只能解决加载问题但如果生产环境黑盒运行你根本不知道哪些资源在真实用户那里经常失败。iloader内置了一个极简的钩子机制在所有关键节点加载失败、重试、降级、超时都会触发事件回调。iloader.on(error, (detail) { // detail.src // detail.type // detail.retryCount // detail.cost reportToMonitor(detail); });上报数据拿来做什么至少三个用途。一是发现某个CDN域名整体异常运维能够第一时间切流量二是定位长期失败的资源反过来驱动业务方修配置三是根据重试次数分布调整加载器的默认参数。我们在接入后的第三天就通过上报发现某个第三方报表脚本在海外网络环境下超时率高达18%单独针对该域名调整了更长超时和更大重试次数最终用户侧几乎无感。另外我在页面上做了一个自愈开关如果关键资源连续失败超过一定阈值加载器会直接通知业务侧渲染一个降级提示页避免用户面对一个看似加载中但永远没反应的僵尸页面。这个设计虽然牺牲了一点体验下限但保护了用户对系统的信任感——一个明确说出错了的页面永远比一个转圈五分钟的页面更友好。8. 我在继续使用iloader过程中的一些体会说句实在话写这个加载器最初只是为了一次事故的善后但真正做完后我最大的感受是动态加载的问题不是某个脚本函数能解决的而是一整套策略的组合。你在管理一个页面的资源加载时本质上是在做一个小型的资源调度系统——并发、优先级、重试、降级、监控每一项单独拿出来都不难但组合在一起并经过线上检验才真正变成可靠的基础设施。到了后期iloader的代码量已经很少变动了反而是在接入新业务时不断遇到新场景迫使我去思考边界的延伸。比如现在的新项目已经考虑和React的Suspense集成让动态加载的Promise直接对接组件挂载的生命周期还有人建议做成Web Worker里加载纯计算模块的能力这样重型SDK不阻塞主线程。这些方向我大概率会在后续版本里逐步完善。如果你现在维护的项目也面临类似的动态加载混乱局面我的建议是别急着堆业务代码先花一周时间把资源加载的策略层理清楚。把不可控的部分做成可控的把无法感知的部分做成可监控的这套底座稳定之后上层的复杂业务才有资格谈体验。最后分享一个小习惯任何加载器上线前至少要在真实网络环境下模拟一次断网-恢复-断网的整个过程看看你的资源是快速失败还是长时间挂起。我在这个测试里发现过好几个代码review时完全看不出来的问题。网络不可靠是常态加载器必须把这种不可靠当成一等公民来对待而不是事后补救的边角料。