PbootCMS 升级到 V3.2.27 后二次开发后台页面的 jQuery 3.x 兼容性排查步骤

AI智能摘要
PbootCMS V3.2.27将jQuery升至3.7.1,后台二次开发的旧API调用面临失效风险。盲目改代码易引发连锁报错,关键在于利用浏览器开发者工具逐页定位具体报错行,精准替换如.live()等废弃方法。若自定义JS位于核心目录,升级时会被覆盖,如何将代码迁移至独立文件并正确引入,才能确保功能在升级后不丢失?
— 此摘要由AI分析文章内容生成,仅供参考。

PbootCMS V3.2.27 将前后台 jQuery 从 1.12.4 升级到了 3.7.1,这是一个跨越多个主版本的大升级。如果你曾经对后台做过二次开发,在自定义 JS 中使用了旧版 API,升级后很可能会遇到控制台报错或功能异常。下面直接给出排查步骤和改写方案,帮你快速定位问题并完成兼容。

受影响的旧写法

jQuery 从 1.x 到 3.x 移除了大量废弃 API,后台二次开发中最容易中招的包括以下几类:

  • .live():在 jQuery 1.7 后已废弃,3.x 中彻底移除。必须替换为 .on()。
  • .die():与 .live() 对应,同样移除,改用 .off()。
  • .size():返回元素个数,3.x 中移除。直接用 .length 属性代替。
  • .andSelf():在 1.8 后已被 .addBack() 取代,3.x 中移除。
  • $(document).on('ready', fn):这种写法在 3.x 中不再支持。改用 $(document).ready(fn) 或直接 $(fn)。
  • .toggle(fn1, fn2):用于事件切换的语法在 3.x 中被移除。需要拆分为独立的事件绑定或使用自定义逻辑。
  • .error():直接绑定错误事件的方法在 3.x 中移除,改用 .on('error', handler)。
  • $.browser:这个对象在 1.9 后已移除,如果代码中用到了浏览器检测,需要改用特性检测或 Modernizr。

另外,3.x 对 $.parseJSON、$.isArray、$.isFunction 等工具方法也做了清理,不过这些通常影响较小,且在现代浏览器中可以直接使用原生 JSON.parse、Array.isArray 等。

逐页定位报错的方法

升级后不要盲目搜索文件,最直接的方式是打开浏览器开发者工具逐页排查。

  1. 登录后台,按 F12 打开开发者工具,切换到 Console 面板。
  2. 从后台左侧菜单开始,依次点击你二次开发过的每一个功能页面(包括列表页、编辑页、设置页、弹窗等)。
  3. 每打开一个页面,观察 Console 中是否有红色报错信息。常见报错如:
  4. TypeError: $(...).live is not a function
  5. TypeError: $(...).size is not a function
  6. TypeError: $(...).andSelf is not a function
  7. TypeError: $(document).on('ready'... 相关
  8. 点击报错右侧的链接,会跳转到 Sources 面板并定位到具体的 JS 文件和行号。如果报错指向的是压缩后的 jQuery 库本身(如 jquery-3.7.1.min.js),说明是你自定义代码中调用了旧 API,需要找到调用处;如果报错指向 admin.js 或你自己的自定义 JS 文件,直接在那行修改即可。
  9. 如果某个页面没有报错但功能异常(如按钮无反应、弹窗不显示),可以切换到 Network 面板,刷新页面,检查是否有 JS 文件加载失败(404)或报错,同样在 Console 中查看是否有黄色警告。

建议把每个页面的报错信息截图或记录在案,然后统一修改。不要一次性修改所有文件,改一个页面测试一个页面。

改写示例

针对最常见的几种写法,直接给出替换方案:

旧写法新写法
$('.btn').live('click', fn)$(document).on('click', '.btn', fn)
$('.list').size()$('.list').length
$('.item').andSelf()$('.item').addBack()
$(document).on('ready', fn)$(document).ready(fn) 或 $(fn)
$('#box').toggle(fn1, fn2)拆分为 $('#box').on('click', fn1) 和 $('#box').on('click', fn2),或用自定义状态控制
$('#img').error(fn)$('#img').on('error', fn)

如果你的自定义 JS 中还使用了 $.browser,建议改为特性检测,例如:

// 旧写法
if ($.browser.msie) { ... }

// 新写法(特性检测)
if (document.documentMode) { ... }
// 或使用 Modernizr

关于升级对模板目录的影响

PbootCMS 的在线升级机制只覆盖 core 和 apps 目录下的核心文件,不会动 template 目录。因此:

  • 后台二次开发:你添加或修改的 JS 文件如果放在 apps/admin/view/default/js/ 或 core/ 等被升级覆盖的路径下,升级后这些文件会被替换为官方版本,需要重新添加自定义代码。建议提前备份,或把自定义 JS 写成独立文件放在 config/ 或 apps/admin/view/default/ 下不冲突的位置(如新建 myadmin.js),然后在后台模板中单独引入。这样升级时不会丢失。
  • 自定义前台模板:如果你自己开发了前台模板,其中引用的 jQuery 路径是你自己设置的,升级不会修改你的模板文件。你可以继续使用旧版 jQuery 文件(如 jquery-1.12.4.min.js),但建议手动更新到 3.7.1 以修复安全漏洞并兼容现代浏览器。只需将新版 jQuery 文件放到你的模板 js/ 目录下,并修改 head.html 中的引用路径即可。

升级前后的检查清单

  1. 升级前完整备份网站文件和数据库。
  2. 在本地或测试环境先升级,逐页测试所有后台功能。
  3. 升级后立刻检查 Console 报错,按上述方法定位并改写。
  4. 如果自定义 JS 文件较多,建议先用全局搜索工具(如 VS Code 的“在文件中查找”)搜索 .live、.size、.andSelf、on('ready' 等关键词,批量定位。
  5. 测试前台功能,特别是文件上传、表单提交、AJAX 操作等涉及 jQuery 的部分。
  6. 确认无误后再将正式站点升级。

按照以上步骤,大多数后台二次开发页面的兼容性问题都能在半小时内解决。如果遇到其他未列出的旧 API 报错,可以根据报错信息在 jQuery 官方迁移指南中查找对应替换方案。

© 版权声明
THE END
喜欢就支持一下吧
点赞13 分享