Layui 2.8 升级到 2.9+ 无需重写代码，但必须验证 layui.css 加载顺序、lay-edit 移除影响及 table/form 交互逻辑；官方唯一文档为 https://layui.dev，推荐使用 2.9.14 或 2.9.23 版本。
直接说结论：Layui 2.8 升级到 2.9+ 不需要重写代码，但必须验证 layui.css 加载顺序、lay-edit 移除影响、以及自定义模块与新版 table/form 的交互逻辑——这三处是实际项目中 90% 的报错和样式异常来源。
确认当前版本与官方源是否可信
别跳过这步。很多“升级失败”其实源于用了非官方镜像或篡改版。Layui 唯一权威文档地址是 https://layui.dev，所有 Gitee/Github 链接都应指向该域名。若访问卡顿，可临时修改本地 hosts 文件绑定最快 IP（如 163.181.35.177 layui.dev），但上线前必须切回 DNS 正常解析。
- 检查你项目中引用的
layui.js和layui.css是否来自https://unpkg.com/layui@2.9.14/或官网下载包，而非第三方 CDN 或旧版打包产物 - 运行时打开浏览器控制台，执行
layui.v，确认返回值是类似"2.9.14"而非"2.8.x"或undefined - 特别注意：v2.9.4、v2.9.5、v2.9.12 已被官方跳过，不要用；优先选
2.9.14（截至 2024-07-09 最稳）或更新的2.9.23（2026-02-19 发布）
必须手动检查的三大破坏性变更
这些不是“警告”，而是运行时直接失效的点，且错误不报在控制台，只表现为功能静默丢失。
-
layui.css现在是强制依赖：以前只引layui.js就能调layer.alert，现在没layui.css就没样式、按钮错位、弹层无法关闭——必须确保 HTML 中<link rel="stylesheet" href="xxx/layui.css">在<script src="xxx/layui.js">之前加载 -
lay-edit组件已彻底移除：如果你页面里还写着lay-edit属性，它不会报错，但编辑功能完全不生效。替代方案只有两个：layedit（富文本）或外接textarea+ 自定义事件，没有“轻量 inline 编辑”内置方案了 -
table默认行为变化：v2.9.0 起table.render()的defaultToolbar支持自定义导出，但老项目若用toolbar: '#myToolbar'且模板里含未声明的 lay-id，会静默跳过整块 toolbar 渲染——建议统一改用defaultToolbar: true+tool: ['export']显式启用
验证关键组件的实际兼容性
别只测“能渲染”，要测真实业务路径。重点盯住以下组合场景：
-
form.select搜索：v2.9.14 优化了非连续字符匹配（比如搜“北京”能命中“北京市朝阳区”），但若你后端返回的options是动态拼接的字符串而非标准<option value="...">...，搜索会失效——必须确保form.render('select')前 DOM 结构合法 -
radio状态同步：v2.9.14 修复了 JS 修改checked后 UI 不刷新的问题，但前提是你的 radio 必须带name属性且同组 name 一致；若用name="user[gender]"这类带方括号的，需额外调用form.render('radio', 'your-filter') -
laydate日期范围限制：v2.9.11 新增min/max支持函数返回值，但若你传的是字符串如min: '2023-01-01'，在 v2.9+ 里会被自动转为当天 00:00:00，而旧版是当作时间戳处理——建议统一改用毫秒数或new Date()实例
上线前必须跑通的三项检查
迁移不是“替换文件就完事”，这三项漏一项，上线后可能凌晨三点被叫醒。
- 打开所有含
table的页面，手动触发排序、分页、导出，观察控制台是否有Uncaught TypeError: Cannot read properties of undefined (reading 'export')类错误——这是table.export模块未正确加载的典型信号 - 在表单提交前，用 JS 修改任意一个
input的值，再调用form.val('filterName')，确认返回值包含刚改的值；若返回空对象，大概率是form.render()没覆盖到新 DOM 或存在重复 render - 用 Chrome 切换到 Network 标签页，过滤
layui，确认所有资源状态码都是 200 且无 404 ——尤其注意layui.all.js这种全量包在 v2.9+ 中已弃用，若还引用会导致模块冲突
最易被忽略的点：Layui 2.9+ 的 layer.open 默认启用了 moveOut（拖拽出视口限制），但如果你页面有 fixed 定位的遮罩层或侧边栏，它会干扰 layer 的 z-index 计算，导致弹层被盖住。这不是 bug，是 CSS 层叠上下文变更带来的副作用，必须手动加 zIndex: 19891014（官方默认值）或更高来兜底。
