你以为 npm install 能装到最新版？今天 htmx 4 把版本标签这张底牌亮出来了

npm install htmx.org，你跑了一下——版本没变，还是 2.0.10。

不是你的 lockfile 有问题，不是 npm 缓存抽了，是 htmx 团队故意把 4.0 压在 next 标签下面不动，打算一直等到 2027 年初才把 latest 挪过去。

这是什么意思，你一个运维或者前端工程化负责人，应该怎么想这件事？

8 月 28 日发布的 htmx 4.0 是正式版，但团队选择不让大多数开发者自动升级到它。

他们自己在博客里写得清清楚楚：成千上万个线上页面用的是不带版本号的 CDN URL，如果 latest 直接跳到 4.x，这些页面的运行时在一夜之间全变了，没人碰一行代码。这意味着大多数跑 npm install htmx.org 的项目、大多数引用 cdn.jsdelivr.net/npm/htmx.org 的静态站点，此刻跑的还是 htmx 2.x——而 4.0 已经发布三周了，躺在那里没人用。

这不是小版本更新。4.0 底层从 XMLHttpRequest 全面迁移到 fetch()，三大行为变化会影响你线上跑的实际功能，保守策略是合理的。

属性继承从默认变成要主动声明

htmx 2 时代，父元素上的 hx 属性会自动传给子元素。你在父级写一个 hx-confirm="确定？"，子按钮全部弹出确认框。4.0 默认不继承了，想要继承得加 :inherited 后缀：

<!-- 2.x：父级写了，全家桶都弹确认 -->
<form hx-post="/api/submit" hx-confirm="确定提交？">
  <button type="submit">提交</button>  <!-- 自动弹 -->
</form>

<!-- 4.0：需要显式声明 -->
<form hx-post="/api/submit" hx-confirm="确定提交？">
  <button type="submit" hx-confirm:inherited>提交</button>
</form>

这个变化最坑的地方在于：不报错，只是行为静默消失。确认框不弹了，目标元素换错了，没有一行 console 告诉你原因。你跑完 CI、merge 进 production，页面功能半残。这是破坏力最大的变更，团队自己的升级指南把它排第一。

事件名称全部重命名

hx:beforeRequest 变成 htmx:before:request，hx:afterSwap 变成 htmx:after:swap。这个有工具可以扫——npx htmx.org@4.0.0 upgrade-check -- ./templates 能扫出所有用到旧事件名的地方，给你一个清单。

History 缓存不再默认进 localStorage

htmx 2 用 localStorage 缓存页面快照，用户点后退时直接恢复 DOM。4.0 改成了回退时重新发请求，配合浏览器自己的请求缓存保证体验。这个变化影响的是「点后退能不能恢复滚动位置和表单内容」这种细节功能。如果你的应用依赖这个，引入 hx-history-cache 扩展改用 sessionStorage 自己控制。

还有一些小的要注意

hx-delete 不再自动附上 form 的 inputs 了；默认超时从无限改成了 60 秒；4xx 和 5xx 响应现在也会 swap 进目标元素——这对返回错误 HTML 的场景是好事，但需要检查你有没有依赖旧的「4xx 不 swap」行为；hx-vars 删了，要用 hx-vals 加 js: 前缀。

升级到 4.0 给你带来了什么

morph 替换是主要收益。htmx 4 内置了改进过的 idiomorph 算法，局部更新 DOM 时尽量保留现有节点的状态，不用全量替换。这意味着你的计数器、分页状态、输入框内容不会在每次 swap 时丢失。

<form> 的 method 属性现在可以用 hx-swap-oob 做多目标更新，一个请求同时改页头和正文，替代以前需要两个请求的场景。

新扩展里 hx-preload 预加载和 hx-history-cache 最实用。

实际操作建议

如果你是直接责任人：跑一下升级检查器，看看你有多少属性和事件要改。工具地址是官方 CLI，直接对着你的模板目录跑：npx htmx.org@4.0.0 upgrade-check -- ./templates。扫出来你会得到一份需要手动处理的清单。

如果你是工程化负责人：这个版本意味着 npm 的 latest 标签至少会再等几个月才动。你的 CI 如果有 npm install htmx.org，目前拿到的是 2.x，这是故意的。如果你想现在就在 staging 环境测 4.0，需要显式指定版本：npm install htmx.org@4 或者 @next。

htmx 团队给 2.x 的支持承诺是无限期，没有 EOL 时间线。这意味着你可以今天不升，不升也不会被甩下。但也意味着社区里 2.x 和 4.x 的混用会持续一段时间，你的团队迟早要面对这个迁移——主动做比被动做划算。

最后提醒一件事：这个升级是改一行版本号的事，但改完之后的验收成本不低。属性继承的静默失效是那种能绕过 CI 跑到线上才暴露的问题，建议在 staging 环境用真实用户数据跑一遍关键流程再合并。