htmx 大版本升级快速通道7 处破坏性变更逐条落地随时可回滚【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx如果你要完成 htmx 大版本升级1.x → 2.x本文把 CHANGELOG.md 中 2.0.0 的全部破坏性变更拆成按升级顺序执行的 5 个步骤每处变更给可粘贴的代码和一步验证方法末尾附完整回退方案。照做即可在保持线上稳定的前提下换掉核心库。从一个 DELETE 请求的查询串说起升级完前端依赖后后台的删除按钮突然失效请求照发参数却不在请求体里而是变成了 URL 查询串后端读不到参数直接 400。这就是 htmx 1.x 升到 2.x 最常见的翻车现场2.0 同时调整了 3 个全局配置默认值、把全部扩展移出核心发行包、并正式放弃 IE。读完本文你会知道这 7 处变更里哪些打中了你、每处为什么这么改、改回来需要几行代码。30 秒自检你命中了哪些变更你的现状是否受影响及程度页面直接script引入无打包器无影响/dist/htmx.js仍可浏览器加载用import/ RequireJS / Node CommonJS必须改导入路径否则构建产物格式错误在用 SSE 扩展1.x 版本连接会失败SSE 必须升 2.x 版本页面残留hx-ws/hx-sse属性属性在 2.0 被移除需改扩展写法页面存在hx-on属性旧语法废弃同元素出现hx-on:*后旧值被忽略DELETE 接口依赖请求体传参默认改为 URL 查询参数后端可能读不到有跨域请求默认被拦截需显式开启依赖 1.x 的平滑滚动体验swap 后滚动变为瞬时定位自研扩展调用selectAndSwap或依赖makeFragment返回Element必须改写为swap与DocumentFragment产品有 IE 硬性要求无法升 2.x留在 1.x 版本线变更清单按处理优先级分三档必须处理否则升级失败模块系统导入路径换成对应dist文件SSE 扩展升 2.x 版本清掉hx-ws/hx-sse旧属性还在支持 IE 的产品不升级建议处理全站搜索hx-on全部改hx-on:事件名 kebab-case核对 3 个默认值scrollBehavior/methodsThatUseUrlParams/selfRequestsOnly是否符合预期其余扩展统一升 2.x 版本可不动script直引/dist/htmx.js的项目——换文件即完成升级五步完成升级按操作顺序执行第 1 步升级前先定模块文件与扩展版本模块文件拆分现象打包项目升级后import htmx from htmx指向的文件格式与打包器不匹配构建报错或产物异常。原因CHANGELOG.md 2.0.0 条目写明按模块体系拆分为 3 个专属文件避免运行时猜格式。处理按你的模块体系查表模块体系2.x 文件ESMimport/dist/htmx.esm.jsAMDRequireJS/dist/htmx.amd.jsCJSNode/dist/htmx.cjs.jsscript直引/dist/htmx.js无需改动验证跑一次全新构建确认 htmx 产物格式与打包器一致script直引则在控制台执行typeof htmx输出object即通过。扩展拆分SSE 必须 2.x现象升级后 SSE 连接建不起来hx-sse不再有处理逻辑。原因CHANGELOG.md 2.0.0 条目记录扩展已从核心发行包移除、独立分发入口见 www/content/extensions/_index.md。多数 1.x 扩展可在 2.x 下继续跑但SSE 扩展是唯一的硬性要求必须升到 2.x 版本。处理扩展升级后单独引入与核心文件并列script src/dist/htmx.js/script script src/extensions/sse.js/script同时执行rg hx-ws|hx-sse搜出全部旧属性按 www/content/extensions/sse.md 与 www/content/extensions/ws.md 改成扩展写法。验证SSE 端点连上并收到一次推送WebSocket 端点做一轮收发。IE 退役现象功能在 Chrome / Firefox / Safari / Edge 正常IE 下报错或白屏。原因www/content/migration-guide-htmx-1.md 明确 2.0 不再支持 IE而 1.x 版本线会继续支持 IE、在可预见的未来持续维护。处理有 IE 硬需求就把依赖锁在 1.x 不动没有则直接升级。验证按你的浏览器支持矩阵跑一遍核心流程。第 2 步升级后把 3 个默认值按需调回 1.x3 个配置项都定义在 src/htmx.js 的默认配置对象中全部可用htmx.config覆盖配置项源码位置1.x 默认2.x 默认恢复 1.x 行为scrollBehaviorL211smoothinstanthtmx.config.scrollBehavior smoothmethodsThatUseUrlParamsL235[get][get, delete]htmx.config.methodsThatUseUrlParams [get]selfRequestsOnlyL241falsetruehtmx.config.selfRequestsOnly false三行代码恢复 1.x 的平滑滚动现象swap 后视口直接跳到目标位置没有 1.x 的平滑过渡。原因src/htmx.js L3953 与 L3958 在 swap settle 时调用target.scrollIntoView({ block, behavior: htmx.config.scrollBehavior })新默认值instant让滚动变成瞬时定位。处理在初始化脚本执行这一行htmx.config.scrollBehavior smooth;验证触发任意一次 swap观察视口是否带动画移动。DELETE 参数进 URL 的原因与改法现象DELETE 请求体为空参数挂在 URL 查询串上后端 400开场那个故障。原因官方的说法很直白——按 HTTP 规范DELETE本应像GET一样使用查询参数而非请求体2.x 只是把行为修正回规范。判定点在 src/htmx.js L4520methodsThatUseUrlParams.indexOf(verb) 0就编码进 URL。处理后端短期读不了查询串时执行htmx.config.methodsThatUseUrlParams [get];更优解是让后端改读 query 参数规范方向不需要你迁就它。验证打开 Network 面板确认 DELETE 请求的Payload为空、参数出现在 URL 里。跨域请求被静默拦截的处理现象发往非同源地址的 htmx 请求根本不发出去Network 里没有对应记录。原因src/htmx.js L4171 在请求发出前有一道闸门selfRequestsOnly为true2.x 默认时拒绝向非本机来源发请求。这是安全加固页面常混排第三方内容放开跨域等于扩大攻击面。处理确有跨域需求时执行htmx.config.selfRequestsOnly false;这行只放开 htmx 的限制请求能否成功仍取决于服务端 CORS 配置。验证发一次跨域请求确认请求发出且响应正常交换进 DOM。第 3 步语法迁移把 hx-on 全部换成 hx-on:现象hx-on里的处理器不触发新旧语法混在同一元素时旧值被静默忽略。原因CHANGELOG.md 2.0.0 条目写明旧的字符串式hx-on被移除换成hx-on:。收集逻辑在 src/htmx.js L2806-L2820只认hx-on:/data-hx-on:前缀及连字符形式hx-on-。www/content/attributes/hx-on.md 同时规定同一元素上hx-on:*与hx-on不能并用前者存在时后者被忽略。处理注意事件名必须写 kebab-case——HTML 属性名不区分大小写浏览器会把hx-on:htmx:beforeRequest整体小写化camelCase 事件名无法稳定匹配!-- 1.x 旧写法 -- button hx-get/info hx-onhtmx:beforeRequest: alert(Making a request!) htmx:afterRequest: alert(Done making a request!) Get Info! /button !-- 2.x 新写法 -- button hx-get/info hx-on:htmx:before-requestalert(Making a request!) hx-on:htmx:after-requestalert(Done making a request!) Get Info! /button !-- 双冒号简写省略 htmx: 命名空间 -- button hx-get/info hx-on::before-requestalert(Making a request!) Get Info! /button模板语言不允许属性名带冒号时可写hx-on-htmx-before-request/hx-on--before-request规则见 www/content/attributes/hx-on.md。验证执行rg hx-on应无残留排除hx-on:行再在 1~2 个改造过的元素上确认处理器实际触发。第 4 步内部 API 两处变更扩展作者重点看makeFragment 返回值统一为 DocumentFragment现象靠「返回的是Element还是DocumentFragment」分支处理的代码升级后走错分支。原因src/htmx.js L608 的实现中html/body开头的响应取 body 子节点、部分 HTML 用内部template包裹解析三条路径一律返回DocumentFragment响应里的title存到fragment.title。处理删掉Element分支按DocumentFragment统一处理const fragment htmx.makeFragment(html); container.appendChild(fragment); // 2.x 下 fragment 恒为 DocumentFragment验证console.log(fragment.constructor.name)输出DocumentFragment。selectAndSwap 移除用 swap 替代现象扩展里调用api.selectAndSwap直接报undefined is not a function。原因www/content/migration-guide-htmx-1.md 与 CHANGELOG.md 2.0.0 条目确认selectAndSwap已移除、由swap取代swap同时挂在内部 API 与公开 API 上实现见 src/htmx.js L1924普通代码也能调htmx.swap()。处理扩展内三步替换let content divHello world/div; // 待交换的 HTML let target api.getTarget(child); // 解析交换目标 let swapSpec api.getSwapSpecification(child); // 读取 hx-swap 规格 api.swap(target, content, swapSpec);不经过扩展、只想换内容时公开 API 一行完成htmx.swap(#output, divSwapped!/div, { swapStyle: innerHTML });swapSpec必填swapStyleinnerHTML/outerHTML/beforebegin等可选swapDelay/settleDelay/transition/ignoreTitle/head与滚动参数swapOptions支持select、selectOOB、contextElement与回调完整签名见 www/content/api.md 的htmx.swap一节。验证跑一遍扩展测试用例或手动触发一次htmx.swap确认内容换入且htmx:afterSwap事件发出。第 5 步升级后按序执行 6 项验证页面加载控制台无报错htmx版本为 2.x事件请求周期各触发一次重点看htmx:before-request/htmx:after-request请求DELETE 参数位置符合预期query 或 body取决于你恢复没恢复跨域有跨域请求时确认未被拦截扩展SSE / WS 各收发一次搜索代码库确认selectAndSwap零残留排障速查表症状可能原因处理DELETE 请求体为空参数跑到 URL2.x 默认把delete编进查询参数后端改读 query或设methodsThatUseUrlParams [get]跨域请求不发出去selfRequestsOnly默认true设selfRequestsOnly false并确认服务端 CORSswap 后滚动没有平滑过渡scrollBehavior默认instant设scrollBehavior smoothhx-on:处理器不触发事件名没写 kebab-case属性名被浏览器小写化改hx-on:htmx:before-request旧hx-on值被静默忽略同元素已存在hx-on:*删掉旧属性统一新语法SSE 连接建不起来SSE 扩展仍是 1.x 版本升级到 2.x 版本hx-ws/hx-sse完全无效属性已在 2.0 移除改为对应扩展写法打包器导入报错模块文件路径未切换按第 1 步表格指向对应文件IE 下白屏2.0 不支持 IE停留在 1.x 版本线回退方案回退分 3 层任一层可独立执行文件层保留旧版htmx.js1.x或在package.json锁回 1.x 版本换回去即可恢复已改写的hx-on:*属性在 1.x 下不生效建议 HTML 与文件一起回滚配置层3 行htmx.config赋值没有耦合删掉即还原 2.x 默认扩展层SSE 扩展退回 1.x 版本恢复hx-ws/hx-sse旧属性升级期间保留 3 样东西旧dist文件或 git tag、迁移前的 HTML 全量 diff、覆盖 DELETE / 跨域 / SSE 的一页回归测试。回退耗时从分钟级到小时级取决于你留了多少。收尾三句口诀先自检再升级恢复 3 个默认值再逐项验证出问题就退回 1.x 版本线。FAQQ1.x 和 2.x 能同站并行吗能分产品线并行——有 IE 需求的站点锁 1.x其余站点上 2.x但同一页面内两个版本会争抢htmx全局对象不要共存。Q旧hx-on不报错了是不是还能用不能。同元素存在hx-on:*时旧值被直接忽略2.x 的收集逻辑src/htmx.js L2806只识别新语法前缀。以「处理器是否真的触发」为准不要以「没报错」为准。Q升级后如何确认一切正常按第 5 步的 6 项清单逐项执行其中控制台无报错、请求参数位置、跨域与 SSE 各占一项全部通过再合入主线。【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考