异步循环下jQuery($)变undefined问题排查咨询

云上老周

2026-8-28

问题根因

书签小工具直接运行在目标页面的全局作用域，await关键字会暂时让出JS主线程，让事件循环队列里排队的其他页面脚本优先执行。第一次循环能正常运行，是因为初始状态下全局$指向jQuery；第一次await UI_Render()让出线程的空窗期里，页面自带的脚本（常见于企业内部系统的模块化加载器、多版本jQuery切换逻辑、全局变量清理逻辑）会把全局window.$覆盖为undefined，等下一次循环执行到依赖jQuery的逻辑时，就会直接崩溃。
你之前用临时变量缓存再回写$的方案本质是和页面脚本抢全局变量的写入权，仅在部分时机下碰巧生效，完全不可靠：只要页面脚本修改$的时机晚于你回写的时机，依然会触发报错。

修复&优化方案

从根源隔离全局变量影响：在书签工具代码最开头就把jQuery引用缓存到私有作用域，后续所有逻辑都使用私有缓存的引用，完全不依赖全局$的状态。推荐用立即执行函数（IIFE）包裹所有工具逻辑，既避免自己的变量被页面逻辑覆盖，也不会污染页面全局作用域，参考实现：

(function() {
  // 初始化第一时间缓存jQuery，后续全程使用私有引用，不受全局变量变动影响
  const _$ = window.jQuery || window.$;
  if (!_$) throw new Error('页面未加载jQuery，自动化工具无法启动');

  async function DoStuff(index) {
    // 所有DOM操作、jQuery调用都用_$，不要直接用全局$
    // 你的业务逻辑写在这里
    return Promise.resolve();
  }

  async function UI_ProgressBar(percent) {
    _$('#auto-progress-bar').css('width', `${percent}%`).text(`进度：${percent}%`);
    return Promise.resolve();
  }

  // 用requestAnimationFrame替代固定10ms延时，浏览器会在下次重绘前执行回调，既保证DOM更新实时可见，又没有多余等待
  function UI_Render() {
    return new Promise(resolve => requestAnimationFrame(() => resolve()));
  }

  // 主逻辑放在内部作用域，不泄露任何变量到全局
  (async function main() {
    for(let i = 0; i <= 100; i++) {
      await DoStuff(i);
      await UI_ProgressBar(i);
      await UI_Render();
    }
  })();
})();

简化异步写法：原代码里await UI_ProgressBar(i).then(async function () { await UI_Render(); })属于冗余写法，直接顺序写await UI_ProgressBar(i); await UI_Render();即可，可读性更高，也减少不必要的Promise链式调用开销。
替换固定延时的渲染等待：把setTimeout(resolve, 10)换成requestAnimationFrame，对DOM更新场景的适配性远好于固定延时，不会因为设备性能差异出现进度条卡顿、更新不及时的问题。

代码风格&实现选型建议

所有书签小工具代码必须用IIFE包裹，绝对不要把自定义函数、变量泄露到全局作用域，避免和页面原有逻辑产生冲突。
所有需要用到的页面全局依赖（比如jQuery、页面挂载的业务请求方法）都要在工具初始化第一时间缓存到私有作用域，不要在异步逻辑里直接读取全局变量——你永远不知道页面其他脚本会在什么时候修改全局变量。
异步逻辑优先用async/await线性写法，非必要不要混用链式.then()和async/await，并行等待场景再用Promise.all/Promise.race即可。
尽量少用固定时长的setTimeout做等待：DOM渲染等待用requestAnimationFrame，等待指定DOM元素出现用MutationObserver，性能和可靠性都远高于轮询+固定延时的方案。

内容的提问来源于stack exchange，提问作者Chirpas