4.2 升级步骤实操：替换、回归与常见报错

五步实操

评估做完就可以动手了。整个替换过程我习惯拆成五步，一步一验证，绝不跳步。

第一步：锁定目标版本

除非有特殊原因，直接锁最新版 2.13.9（2026-08-11）即可——一路修过来的坑，没必要中途再补课。确定后把版本号写进团队约定，甚至写进项目的依赖清单，避免有人顺手拿了旧包，升级到一半出现两个版本混跑的尴尬局面。

第二步：替换文件

替换方式按项目形态二选一：

• 传统引用：去官网下载本地 zip，替换项目里的 layui.css、layui.js 以及整个 layui 目录。替换前先打包备份旧版本，这是回滚的底线，没有备份的替换等于走钢丝。
• npm 管理：更新依赖版本号即可，注意锁住具体版本，避免小版本漂移导致团队各人环境不一致。

替换完成后先别写代码，打开一个引用 layui 的页面确认文件加载路径没变。很多项目把 layui 目录放在自定义路径下，替换时最容易漏的就是路径映射。

第三步：跑通最小页面

不要一上来就全站跑。先选一个最简单的页面，比如登录页，让它在 2.13.9 下完整跑通：样式加载正常、表单能提交、弹层能弹出、日期控件能选择。这一步能挡住八成的基础性问题，比如路径写错、文件没替换全、构建流程没把新文件带上。最小页面跑不通就停下排查，跑通了再扩大范围。

第四步：全页面回归

回归围绕五大高频区展开，这是我多年总结的次序：

回归的诀窍是固定路线：从登录开始，按核心业务流程走一遍，每回归完一块就在清单上打勾。核心业务页逐页过，边缘页可以抽查，但五大高频区涉及的页面一个都不能省。回归时最好两个人一组：一人操作，一人记录，速度比单打独斗快一倍，而且记录的人顺手就能把报错截图归档，后续排查有据可查。

观察控制台报错

回归全程开着控制台，报错当场记下来，不要指望事后回忆。常见报错基本可以归成几类，对号入座处理：

样式错乱这一类最隐蔽：报错栏没有信息，但界面明显不对。多半是旧定制 css 覆盖在新版样式上产生了冲突，逐条注释排查即可定位。遇到表外的问题，先去官方升级指南找对应版本区间的说明，再考虑自己动手改，不要凭感觉改源码。每处理完一个报错，把现象与解法补充到团队的内部文档里，下一次升级就是现成的经验库。

心得：一次只升一个中间版本区间

2.6.8 到 2.13.9 之间隔着 2.8.0、2.10.0、2.11.0、2.12.0、2.13.0 多个节点，我建议分段走：2.6 先升到 2.8 验证一轮，再到 2.10，最后到 2.13，每段跑一遍回归。一步到位不是不行，而是出了问题你不知道是哪个区间引入的，排查范围太大。分段验证多花的是时间，省下的是深夜排查的头发。

官方在 layui.dev 的 notes 区提供了 2.8 以来的升级指南，社区在 GitHub 上也整理过 2.x 系列的升级变化清单。每升一段前先翻一遍对应章节，心里有底再动手。

回归顺序也有讲究

回归不要按目录顺序漫无目的地点。建议按“用户流量排序”：先跑登录和首页，再跑核心业务流程里最常见的表格增删改查，然后是弹层与表单提交，最后才轮到上传、日期这类低频组件。原因很简单——高频路径一旦出问题，业务立刻停摆；低频组件即便有小毛病，也有缓冲时间修。

另外，回归时开着浏览器控制台是铁律。很多升级问题不会立刻表现为界面异常，而是先在控制台里留下警告，比如弃用方法的提示、样式覆盖的告警。带着控制台跑完一轮，等于把问题提前暴露了一大半，比等测试同事报 bug 快得多。