jQuery 旧项目维护与迁移地图：ready、事件、Ajax、性能和 jQuery 4

jQuery 仍常见于存量后台、主题和插件项目，但它不是新的浏览器兼容万能层。官方 jQuery 4.0 已于 2026 年发布：移除了部分废弃 API、收紧旧浏览器支持，并调整 slim build。维护前先盘点实际版本、插件和浏览器矩阵，再决定升级、保留或逐页迁移，别只替换 CDN 地址。

DOM ready 不等于所有资源加载完成

$(fn) 与 $(document).ready(fn) 等待 DOM 可用，适合查找页面节点；window.load 会等图片等资源也完成。图片尺寸、Canvas 初始化或依赖字体布局的工作要依据具体需求选时机，不要把所有初始化都延迟到 load，也不要假设 ready 后图片已经加载完。

$(function () {
  const $root = $('#account-form');
  if (!$root.length) return;

  $root.on('submit.account', (event) => {
    event.preventDefault();
    // 这里仅处理界面反馈；身份和数据仍由服务端验证。
  });
});

jQuery 集合和 DOM 节点不是一回事

$('#save') 返回 jQuery 集合，即使只匹配一个节点也仍是集合；document.querySelector() 返回 DOM 节点或 null。可用 .get(0) / [0] 取原生节点，用 $(node) 包装后调用 jQuery 方法。先判断 .length，不要把集合当数组，也不要对集合调用原生节点属性。

集合上的 setter 通常隐式迭代；getter 常取第一个匹配项。.each() 适合逐项副作用，回调中的 this 是当前 DOM 节点；.map() 产生转换结果，不应拿来代替副作用循环。链式方法在遇到 getter、原生 Promise 或返回其他类型时会断开，拆变量比依赖难读的链更稳。

事件、委托与键盘

新旧 API 中，.on() / .off() 是统一的事件绑定和清理入口；旧 .bind()、.delegate()、.live() 不宜继续扩散。动态子节点可在稳定容器上做委托，命名空间可让组件准确解绑。不要无参数调用 .off() 删除其它模块处理器。用户操作用 event.key 表达语义键位，旧 keyCode 已不适合新代码；方向键、Enter、Escape 和输入法组合状态需要按控件行为分别处理。

event.target 是原始命中的后代；委托处理器的 this 是匹配到的节点，绑定点可从 delegateTarget 理解。return false 会同时阻止默认行为和传播，通常用显式 preventDefault() / stopPropagation()，避免意外阻断其他监听器。

DOM 更新、Ajax 和安全边界

纯文本使用 .text()；.html()、.append(string) 和模板拼接会解析 HTML，不可信字符串进入这些 API 会产生 DOM XSS。节点插入前校验 URL scheme、属性和业务数据；服务端依旧做认证、授权、CSRF 与字段校验。

新代码通常可用 Fetch 和原生 Promise：检查 response.ok，处理网络失败、取消和过期响应。存量 $.ajax() 仍可维护，但要明确超时、失败、返回类型和取消句柄；不要设置同步 XHR，也不要把 JSONP 当成跨域授权。jQuery 4 移除了 JSON 自动升级为 JSONP 的行为，跨域 JSON 应由服务器配置 CORS，凭据与身份验证另行设计。

async function loadItems(signal) {
  const response = await fetch('/api/items', { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

滚动或输入高频事件用 debounce/throttle 降低工作量；动画帧相关视觉更新可用 requestAnimationFrame，懒加载优先用 IntersectionObserver。不要把耗时计算、DOM 读写和多次布局测量都塞进 scroll 回调。

迁移到 jQuery 4 或原生 API

jQuery 4 不再支持 IE 10 及更早版本、Edge Legacy 等旧浏览器；若项目仍要求这些环境，应明确保留兼容版本并规划退出。官方升级指南建议先在开发环境加入对应版本的 jQuery Migrate，消除控制台警告、升级插件并跑回归，再移除 Migrate。生产环境不能长期依赖迁移插件掩盖问题。

对于简单的选择、事件和 class 操作，可逐组件换成 querySelector、addEventListener、classList；有大量成熟 jQuery 插件、复杂表单或 IE 兼容承诺时，不必机械全量重写。升级要核对 jQuery UI、插件、CSP/Trusted Types、Ajax 依赖，以及 full/slim build 的 Deferred/Callbacks 模块差异。

旧总结里夹带的 PHP $_GET、$_POST、$_FILES、Session 和 isset/empty 是服务端知识，不属于 jQuery；已按前后端边界移出本篇，应放到 PHP Web 基础与安全 对应章节。网络 HTTP、CORS 和安全请求则只在前端可观察边界讲解，不代替后端实现。

接手存量项目的顺序

1. 搜索 jQuery 主版本、CDN/本地副本、插件、Migrate 和 $/jQuery 全局冲突。
2. 写下受支持浏览器、页面入口、动态挂载点和需要保留的用户行为。
3. 用测试或录屏固定表单、菜单、轮播、异步请求、动画和键盘路径。
4. 分批修复事件重复、XSS、无清理计时器、布局抖动与无障碍问题。
5. 先用 Migrate 迁主版本；确认插件和回归通过后，再评估逐组件原生化。

参考：jQuery 4.0 Upgrade Guide、jQuery Support Policy、jQuery on、jQuery off、jQuery Ajax、jQuery 4.0 release、MDN classList、MDN Fetch、OWASP XSS Prevention。