2026 年 8 月 28 日，htmx 正式发布 4.0.0。这个以「稳定不换大版本」著称的 HTML 扩展库，上一次发大版本还要追溯到 2023 年的 2.0，而这次它不仅跨了一个大版本号，还直接跳过了 3——官方在公告里给出的理由是 8 个月的重写：整个网络层从 XMLHttpRequest 迁移到了 fetch()。
htmx 的核心思路是在 HTML 里用 hx-get、hx-post 这类属性声明交互行为，由库负责发请求、把服务器返回的 HTML 片段插进页面，浏览器端基本不需要写 JavaScript。这个模式在 2023 年前后随着「HTML 超媒体」理念的回潮而流行，GitHub 上积累了 4 万多 star。对大量 Django、Rails、Go 后端项目来说，htmx 是「不写前端框架也能做出动态页面」的默认答案，所以 4.0 里每一个破坏性变化都会落到成千上万个存量项目头上。
网络层换血：XMLHttpRequest 退役
htmx 4 内部最大的工程是把请求层整体迁移到 fetch() API。XMLHttpRequest 是 2000 年代初的产物，htmx 一直沿用它的根本考量是向后兼容：老浏览器支持。官方公告提到，创始人在做极简实验项目 fixi 的过程中重新熟悉了 fetch() 和现代 JavaScript 的异步模型，意识到迁走之后流式响应这类需求会简单得多，于是拉起了四人核心团队重写。
对普通用户来说这次迁移是透明的，请求照发、HTML 照换。真正的区别藏在三个地方：
htmx:xhr:*系列事件被移除，请求生命周期事件统一挂到新命名体系下；- 默认请求超时从「无限等待」改为 60 秒，长轮询类应用需要显式调回 0；
- 基于 fetch 的扩展生态成为可能，SSE、WebSocket、multipart 流式扩展全部按新模型重写。
第三点是这次大版本最实在的收益。htmx 2 时代的流式支持靠的是在 XHR 上做变通，而 fetch 原生支持 ReadableStream，公告里反复强调的 streaming HTML（服务器一点点吐 HTML、页面边收边渲染）在新架构下是一等公民。
最大升级负担：属性继承改为显式声明
htmx 有个从 intercooler.js 时代继承下来的行为：父元素上的很多 hx-* 属性会自动向下传递给子元素。这个设计模仿 CSS 的层叠机制，好处是可以在容器上写一次 hx-confirm，内部所有按钮都弹确认框；代价是行为不直观——读代码时很难判断某个属性到底在哪个元素上生效，出了问题也不容易定位。
htmx 4 把默认行为翻转了：属性不再自动继承，需要继承时在属性名后加 :inherited 后缀：
Delete
Delete
官方明确说这是迁移 2.x 项目时最大的升级负担。一个典型场景是 CSRF：很多项目把 hx-headers 写在 `` 上给全站请求带 token，升级后这行如果不加 :inherited，子元素的请求就不再携带 token，服务器会直接拒绝。配套的 hx-disinherit 和 hx-inherit 属性被移除，它们在新默认行为下失去了存在意义；反过来 :append 修饰符是新增的，用于在继承值上追加而不是覆盖。
为了降低排查成本，官方发布了命令行升级检查器，扫描 HTML、模板文件（Jinja、ERB、Handlebars 等）和 JS/TS 源码，逐条列出需要补 :inherited 的位置。官方公告里的示例输出很能说明问题的普遍性：一个 9 行的模板文件里检出 8 处，包括 CSRF header 继承失效、属性改名、事件旧名等三类问题。项目还附带了一个面向 AI 编程助手的 agent skill，让 Claude 这类工具直接接手批量升级。
事件名规范化与错误处理的转向
htmx 2 的事件名是十年间自然生长出来的，命名风格混杂。4.0 把所有事件统一为 htmx:阶段:动作 的格式：htmx:beforeRequest 变成 htmx:before:request，htmx:afterSwap 变成 htmx:after:swap。散落的四个错误事件（sendError、swapError、targetError、timeout）合并成一个 htmx:error，HTTP 错误响应单独走 htmx:response:error。
改名之外，错误处理的语义变化影响更大。htmx 2 收到 4xx/5xx 响应时静默丢弃，页面上什么都不发生，用户对着一个没反应的按钮。htmx 4 改为：除了 204 和 304，所有 HTTP 响应都会执行 swap——服务器返回带 422 状态码的表单错误 HTML，会直接渲染到目标位置。前端框架流行之后，「错误响应也是合法的 UI 内容」已经是普遍共识，htmx 这次算是把默认行为拉齐了。想保留老行为的，可以用 hx-status 按状态码逐个控制，或一行配置切回全局不换。
另外两个小变化容易被忽略但会影响存量代码：hx-delete 不再自动携带所在表单的输入（与 hx-get 对齐），需要的地方补 hx-include；hx-disable 被重命名为 hx-ignore，hx-disable 这个名字改成承担原来 hx-disabled-elt 的职责（请求期间禁用元素）。官方特别提醒这两个改名要在升级前先做，避免语义冲突。
History 机制的减法
htmx 2 的浏览器历史支持把页面快照存进 localStorage，返回时恢复。这个快照机制是历年支持工单的重灾区：快照里包含第三方脚本对 DOM 的改动，恢复时 DOM 是改过的，但第三方脚本的逻辑没有跟着恢复，页面状态就错了。
htmx 4 直接砍掉了 localStorage 缓存：后退时重新请求页面再 swap 进来。行为变得可预测，第三方库「天然正常」，配合 HTTP 缓存速度也不差。确实需要本地缓存的应用可以启用官方的 hx-history-cache 扩展，从 sessionStorage 恢复，并为 Alpine.js 这类脚本方案做了适配。
新东西：morph swap 与 hx-partial
两个值得单独说的新特性。第一是 morph swap 内置。htmx 2 时代换内容是整体替换，后来官方另开了 idiomorph 项目做 DOM 形态匹配（只更新变化的节点，保留输入框焦点、动画状态），但一直没有合进主库。4.0 里 morph 算法经过改进后开箱即用，配置项里还能控制 morph 扫描上限、跳过选择器等细节。
第二是新标签 。htmx 的 out-of-band swap 机制允许一个响应同时更新页面多个位置，但语法是把 `hx-swap-oob` 属性挂在响应 HTML 的元素上，写起来绕。 把「这段 HTML 渲染到哪个目标」直接写进标签属性：
新消息
5
一段响应里可以放多个 partial，各自指定目标和插入方式，比 OOB 语法的表达力强一截。
扩展生态与 htmx 自己的「Alpine」
4.0 的扩展系统整体重做：扩展脚本直接用 `` 引入即生效，hx-ext 属性被移除；可以用 meta 标签声明白名单限制可加载的扩展；扩展作者用 htmx.registerExtension() 注册。官方现在随主库维护一批核心扩展，除前面提到的流式三件套（SSE、WebSocket、multipart）和 history 缓存，还包括 hover 预加载、原生文件下载、CSP 严格模式适配、与 Alpine.js 共存的兼容层等。发行包里新增 htmax.js 打包，把 htmx 和最常用的扩展合进一个文件。
最受关注的新扩展是 hx-live，官方自己做的轻量前端脚本方案，灵感来自 Alpine.js、jQuery 和自家此前的 hyperscript。它在 htmx 的 HATEOAS 模型上补了「DOM 内响应式」这块拼图，官方称其为 DOM-based reactivity。htmx 社区里「htmx 管请求、Alpine 管客户端状态」一直是常见组合，hx-live 出现后，这个组合是否还需要第二个库，交给 4.x 时期的社区取舍。GA 之前 htmx 作者在 HN 讨论里也回应过相关担忧：显式继承的默认值变化可能会让大量见过 htmx 2 训练数据的 AI 模型输出旧写法，但团队认为这是对的事。
为什么跳过 3.0，以及升级节奏
htmx 作者在 2.0 发布时公开承诺过不再有破坏性升级的大版本。后来重写计划启动，团队面临的选项是违背承诺或者换个方式守约，最终 chosen 的方案是直接跳到 4.0——版本号 3 被永久空出，作为「没有 3」这个承诺的延续。HN 上获得高赞的解释很简洁：他们确实需要一次破坏性变更，唯一不食言的方式就是不发 3。
升级节奏上官方给出了少见的保守方案：NPM 的 latest 标签继续指向 2.x，4.0 挂在 next 上，到 2027 年初才会切换。原因是不希望靠非版本化 CDN URL 引入 htmx 的用户（比如直接引 htmx.org@2 的路径）某天打开页面突然加载了大版本。2.x 线无限期维护，官方同时提供 htmx-2-compat 扩展，在 4.0 上还原 2.x 的默认行为和事件名，给大型存量项目留出渐进迁移的通道。
对正在用 htmx 的团队，可行的路径是：先跑 npx [email protected] upgrade-check 盘点存量代码（新项目直接用 4.0 无历史包袱）；新起的页面默认继承需要多写几个字，但换来的是行为可读；重度依赖 localStorage 历史、OOB 顺序或 queue 触发器的项目放缓节奏，等 htmx-2-compat 或对应扩展补齐后再动。完整变更清单见官方 What's New in htmx 4 文档，从事件、配置项到扩展逐一列了对照表。
htmx 4 的三个关键词是请求层现代化、行为显式化、流式响应标配，剩下的交给服务器渲染的 HTML。前端生态过去几年在复杂度上一路狂奔，htmx 反向做减法还能维持百万级周下载量，这次 4.0 证明的只是它在认真维护这件事本身。
参考来源：