请求指导：将JQuery Migrate从1.4.1升级至最新稳定版3.4.0

一、升级前准备 #

• 先确认当前项目搭配的jQuery版本：Migrate 1.4.1对应jQuery 1.x/2.x，而3.4.0必须搭配jQuery 3.x（建议用3.6.0及以上的稳定版，Migrate 3.4.0是专门适配jQuery 3.x的）
• 备份当前代码库，最好拉个新分支专门做升级，别直接动主分支
• 打开浏览器控制台的所有日志级别（包括警告），Migrate会输出所有兼容提示，这是找问题的核心

二、替换库文件 #

• 删掉旧的jquery-migrate-1.4.1.js，引入jquery-migrate-3.4.0.js——注意顺序：先引jQuery 3.x，再引Migrate 3.4.0，搞反了会出问题
• 如果用npm/yarn管理依赖，直接跑命令：

  npm uninstall jquery-migrate@1.4.1
  npm install jquery@^3.6.4 jquery-migrate@3.4.0 --save
  

三、排查修复兼容问题 #

Migrate 3.x会把1.x/2.x里废弃、移除的API行为转成警告或错误，重点盯这些常见坑：

• 废弃的事件绑定方法：.bind()、.unbind()、.delegate()、.undelegate()全换成.on()、.off()
  举个例子：
  旧代码：$('.btn').bind('click', handleClick);
  新代码：$('.btn').on('click', handleClick);
• jQuery 3.x核心API变动：
  • $.ajax()的success/error/complete回调别用了，换成done()/fail()/always()，或者直接用Promise语法
  • $.each()遍历数组时，参数顺序从(index, value)改成了和原生JS一致的(value, index)——Migrate会兼容，但最好改成标准写法，避免后续出问题
  • $.browser、$.sub()这些属性方法直接没了，换用特性检测替代$.browser，比如判断某个API是否存在来做兼容
• Migrate 3.x砍掉的兼容特性：
  • 别用$.parseJSON()了，直接用原生JSON.parse()
  • 老版本的toggle()（同时管显示隐藏和事件切换的那个）被移除了：如果是用来切换元素显示，改用.toggleClass()或者直接操作style.display；如果是事件切换，自己写逻辑实现
• 选择器严格化：jQuery 3.x严格遵循CSS标准，比如$('[href=#]')会报错，要改成$('[href="#"]')

四、分阶段测试 #

• 先在开发环境全量测，逐个页面验证：表单提交、按钮点击、AJAX请求、DOM操作这些核心功能
• 控制台每出一个Migrate警告，就修一个，直到完全没警告为止
• 如果项目复杂，可以先带着Migrate 3.4.0跑一段时间，等所有兼容问题都搞定了，再考虑要不要移除Migrate库（如果不需要兼容旧代码的话）

五、上线后监控 #

• 上线后盯紧浏览器控制台的错误日志，尤其是用户反馈的异常情况
• 可以在生产环境暂时保留Migrate的日志输出（别影响性能就行），收集遗漏的兼容问题

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