<!-- title: htmx 4.0：删出来的大版本升级 -->
<!-- domain: programming -->
<!-- video: https://www.youtube.com/watch?v=qhfgXVVNYL0 -->

# htmx 4.0：删出来的大版本升级

## 为什么这个视频值得你花12分钟

就在昨天——2026年8月28日，htmx 4.0.0 正式发布，冲上 Hacker News 首页第二位（472 points）。而在正式版落地一个多月前，YouTube 频道 **Cloud Codes** 就发布了一期目前该话题下观看量最高的深度拆解视频《HTMX 4.0 Is Here - And There's No HTMX 3 (Here's Why)》，把整个 4.0 的技术内幕、破坏性变更和迁移策略讲透了。

这个视频解决的是一个非常具体的问题：**一个作者公开承诺“永远不会有 3.0 版本”的库，为什么突然跳号发布了 4.0？这算不算食言？升级到底会弄坏什么？** 它不给情怀答案，而是逐行拆代码、逐条列变更，最后还给出“你到底该不该升级”的决策框架。在 AI 框架新闻满天飞、Web 前端“每18个月重学一遍”的今天，这是一期难得的、关于软件工程承诺与克制的深度内容。

## 视频背景卡片

| 项目 | 内容 |
|------|------|
| 视频标题 | HTMX 4.0 Is Here - And There's No HTMX 3 (Here's Why) |
| 频道 | Cloud Codes |
| 发布日期 | 2026-07-27（基于 beta6 制作；4.0.0 正式版已于 2026-08-28 落地） |
| 时长 | 12分10秒 |
| 播放量 | 约1.96万（截至今日抓取） |
| 核心主题 | htmx 跳过 3.0 直发 4.0 的技术内幕：fetch() 重构、三大破坏性变更、迁移策略与版本哲学 |

## 核心内容拆解

### 要点一：先厘清时间线——视频拆的是 beta6，正式版昨天刚发布

这期视频发布于7月27日，拆解的是 npm 上的 `4.0.0-beta6`（7月23日发布）。视频里的关键判断——"4.0 还不是 latest tag，官方仍推荐新手装 2.0"——在8月28日正式版发布后依然成立：htmx 官方公告明确写道，**4.0 不会立即标记为 NPM 的 `latest`，2.x 将继续保持 `latest`，4.0 线保持 `next`，直到2027年初的某个时间点**，目的是不强迫那些使用无版本号 CDN 链接的用户被动升级。

换句话说：这个视频的时效性不但没过时，反而是目前理解 htmx 4.0 最完整的地图。官方公告的措辞也印证了视频的判断："htmx 2 will continue to be supported indefinitely so don't feel any pressure to upgrade"（htmx 2 将被无限期支持，升级毫无压力）。

### 要点二：为什么没有 htmx 3？一个承诺的字面与精神

这是整个故事最有戏剧性的部分。2023年，htmx 作者 Carson Gross（蒙大拿州的计算机科学教授）公开承诺："There will never be an HTMX 3"——不会有 htmx 3。这不是营销话术，而是他“完成式软件”（finished software）哲学的宣言：一个库应该做到它该做的事，然后永远做下去，而不是每隔18个月拖着他的用户重写一遍应用。

然后尴尬来了：他决定把库的底层管道从老掉牙的 XMLHttpRequest 换成 fetch()——这个改动**无论如何都不可能不破坏兼容性**。摆在面前的选择只有两个：食言发 htmx 3，或者干脆不做这个改进。他选了第三扇门：**跳过数字3，直接发4**。视频引用了他的原话："I said there would not be a version 3 of htmx. But technically, I said nothing about a version 4."（我说过不会有 htmx 3，但严格来讲，我可没说过不会有 htmx 4。）

你可以把这解读成律师话术，但视频给出了一个更有说服力的判断框架：**衡量承诺不能只看数字，要看他有没有让用户被迫迁移**。后面你会看到，他用“永久支持 + 多年滚动发布 + 官方兼容层”把承诺的精神兑现得比大多数框架的字面承诺还扎实。

### 要点三：The fetch()ening——13KB玩具库挖出的20年老管道

为什么非换不可？转折点发生在2025年1月：Carson 写了一个叫 **fixi.js** 的玩具库——一个只有几百行的极简版 htmx，第一行代码就基于 fetch 和 async/await。视频提到它目前约1300个 star，本来没打算发布。但给自己最受欢迎的作品写一个“竞品”，效果相当于照了一次X光：**htmx 的 API 没问题，问题藏在底层——那是五年堆出来的兼容性补丁，垫在一个为了 Internet Explorer 而设计的请求对象上。**

XMLHttpRequest 是2000年代初的产物，回调式、前 Promise 时代的 API，它的很多怪癖源于早已不再重要的 IE 兼容。fetch 是基于 Promise 的现代标准。替换的结果符合这个发布的整体气质——**这是一个靠做减法的大版本**：视频给出的数据是 htmx 2.10 压缩后约 50KB，beta6 缩到 35.4KB，同样的核心属性，减掉了约15KB的“历史遗留 workaround"。（注意：社区常说的"htmx 只有14-16KB”指的是 gzip 压缩后的传输体积，两个口径并不矛盾。）

但 fetch 带来的不只是瘦身。它解锁了 XMLHttpRequest 给不了的能力——**流式响应（readable streams）**：服务器可以边生成边发送，页面边到达边渲染。这一点在要点七会展开，它是整期视频里最有前瞻性的论点。

### 要点四：作者亲口承认的“最大错误”——隐式继承之死

htmx 4 第二个重大变更，是 Carson Gross 用第一人称认领的设计失误。在 htmx 1.0 和 2.0 里，很多属性会**沿 DOM 树隐式继承**：你在某个 `div` 上写 `hx-confirm="Are you sure?"`，它下面所有层级的元素都会默默继承这个行为。他的原话（视频和官方迁移指南都引用了）："Making attribute inheritance implicit was the biggest mistake in htmx 1.0 and 2.0."

为什么这是大错误？视频举的场景每个前端都经历过：深夜调试，某个按钮的行为解释不通，最后发现是一个四层之外、八个月前为别的需求加的属性在作祟。**隐式行为就是不可见行为**——这和全局变量、CSS 选择器级联是同一类问题：写的时候省三秒，读的时候花三小时。这也违背了 htmx 社区自己奉为圭臬的 Locality of Behavior（行为局部性）原则。

htmx 4 的解法干脆利落：默认不继承，想继承就显式声明——

```html
<!-- htmx 2：confirm 会泄漏给所有子元素 -->
<div hx-confirm="Are you sure?">

<!-- htmx 4：不声明就不继承 -->
<div hx-confirm:inherited="Are you sure?">
```

视频还给出了一个实用的退路：一行配置 `htmx.config.inheritctInheritance = true`（隐式继承开关）可以让老应用先跑起来再慢慢改。官方甚至配了 CLI 工具自动扫描需要加 `:inherited` 后缀的位置。**一个维护者公开承认自己最常用的功能是设计错误，然后不惜破坏兼容性也要改掉——这在基础设施软件里是稀缺品质。**

### 要点五：删掉最聪明的功能——“退回1998”的历史缓存

三个大变更里，视频认为这个“最安静但最有教育意义”。htmx 2 加速“后退按钮”的方式很聪明：导航时把整个 DOM 快照存进 localStorage，按后退键时瞬间恢复。快是真的快，脆也是真的脆——DOM 快照定格的是一个时刻，而时刻里塞满了冻不住的东西：第三方脚本改过的页面、组件内部状态、播放到一半的媒体。出问题时，故障诡异且难以复现——这是最坏的 bug 类型。视频引用了支持团队的经验之谈：“当修复一个功能的方法是关掉这个功能，那这个功能本身就是 bug。"

htmx 4 的方案：按后退键？**重新向服务器请求这个页面**，和1998年的浏览器做的一样。最好情况下略慢，但每一种情况下都正确。想要缓存的，官方提供了可选的 `hx-history-cache` 扩展（基于 sessionStorage），默认关闭。

我的延伸分析：这是整期视频里最值得所有工程师带走的判断——**成熟项目的信号往往不是又加了什么，而是敢于删除一个“聪明但脆弱”的功能，换回一个“无聊但永远有效”的方案。** 这个标准和具体的 htmx 无关。

### 要点六：破坏性清单与迁移工具——“预算一个项目，而不是一个下午”

视频没有回避迁移成本，反而用了整个章节列清单。核心破坏点：

- **4xx/5xx 响应现在会 swap 了**（除204/304）。多数情况这是你想要的——服务器返回带校验错误的表单和422状态码，零配置直接渲染进目标位置；但如果你有个返回整页HTML的500处理器，htmx 4 会把整个错误页塞进你布局里的一个 div。可以用 `hx-status` 或全局配置换回老规则，或者直接上官方的 **htmx2 compat 扩展**（一个 script 标签恢复旧继承、旧事件名、旧错误规则），先让应用跑起来，再一片一片拆。
- **24个事件改名**，统一为 `htmx:phase:action` 语法（如 `htmx:beforeRequest` → `htmx:before:request`），4个错误事件合并为 `htmx:error`。最阴险的是：监听旧事件的 JS **不会报错，只会静默失效**。
- **属性大清洗**：8个属性删除、5个改名。特别要注意 `hx-disable` 的语义换位（现在屏蔽处理的是 `hx-ignore`），视频提醒：先改这个，否则迁移中途两者会撞车。
- 两个体感默认值：请求默认60秒超时（以前无限挂起）、settle 延迟从20ms降到1ms。

官方配套的迁移工具 `npx htmx.org@4.0.0 upgrade-check` 能扫描 HTML/PHP/JS/TS/Jinja/ERB 等文件，按文件和行号打印问题。视频没提到、但正式版公告里新增的亮点是：**官方同时发布了4个 agent skill 文件**（`htmx-guidance`、`htmx-debugging`、`htmx-extension-authoring`、`htmx-upgrade-from-htmx2`），直接给 AI 编程助手喂迁移知识——这大概是2026年发新版本的标准动作了。视频的结论很务实：大应用迁移“要预算一个项目，不是一个下午”，但 2.x 永久支持意味着**你没有任何截止日期**。

### 要点七：最被低估的论点——hypermedia 可能是对 AI Agent 最友好的 Web 架构

这是视频中段抛出、我认为最有传播价值的一组推理（Signal Coders 的同题视频也独立提出了类似观点，值得交叉参考）：

1. **一个接缝取代五个**。让 AI 给现代前端加功能，它要同时改服务端代码、API schema、客户端数据层、状态管理、组件树，并保持全部一致——每个接缝都是一个“自信地编造一个不存在的 endpoint”的机会。hypermedia 应用里，改动通常收敛为“一个 handler + 一个模板”。接缝少，幻觉就少。
2. **输出可验证**。Agent 写出的 HTML 是能直接看的；Agent 写的状态管理代码是“看起来没问题、三周后在某个特定交互序列里炸掉”的。在人人都在审阅机器生成代码的今天，**正确性肉眼可见的架构有真实优势**。
3. **上下文需求更小**。Agent 需要装进脑子里的系统细节越少，错误越少、成本越低、小模型（包括本地模型）表现越好。
4. **流式的天然契合**。这是 fetch 化最实际的红利：LLM 的输出本来就是 token 流，htmx 4 的内核现在原生说“流”这门语言。以前在 hypermedia 应用里做 AI 功能，流式渲染恰恰是简单方案崩溃、你被迫抓起前端框架的场景——现在一个 SSE 扩展加几个属性就够。

视频也诚实地给出了反方：**训练数据偏差是真实存在的**。你让模型写 React 组件，得到的是流畅地道的答案；让它写复杂的 htmx，可能得到十年前的老写法。作者的判断是：架构优势是结构性的、永久的；训练数据劣势是暂时的、正在收缩的。我认同这个排序，但会加一个提醒：这两者的交叉点大概就在未来一两年，现在入场 htmx 的团队反而可能在“AI 写 hypermedia”这个训练数据还不拥挤的赛道上积累先发语料。

### 要点八：永久支持与 Drupal——被主流报道跳过的采用信号

视频的收尾把格局拉开了。htmx 4 发布伴随三个承诺：**htmx 2 永久支持**（对 htmx 1.x 和更早的 intercooler.js 也是同样承诺，且后两者今天仍在服役——这是已经兑现过一次的记录，不是空头支票）；**多年滚动发布**（4.0 到2027年初才接管 latest tag）；**全程公开开发**。

另一个几乎没人报道的信号（此条仅见于 Signal Coders 视频的说法，官方渠道我未交叉验证，请注意甄别）：**Drupal——这个服役20年、装机量巨大、工程文化极度保守的 CMS——正在把核心 Ajax 系统重建在 htmx 上**，作为官方 initiative 公开追踪，直接对着 4.0 的 beta 测试并向 htmx 团队反馈（beta 期间恢复 `data-hx-` 前缀语法的决定据说就来自这轮反馈）。一个最怕折腾的平台选择在预发布版本上公开下注，这比任何 benchmark 都有说服力。

顺带一个彩蛋：htmx 4 的发布还配了一个“游戏”——官方公告的致谢里专门感谢了“游戏背后的天才” Stephen Mitchell，YouTube 上甚至有“htmx 4.0 发布在 Game Boy 卡带上”的整活视频。这个社区的一贯画风：认真到极致，也玩到极致。

## 知识结构图

```mermaid
flowchart TD
    A["htmx 4.0.0<br/>2026-08-28 正式发布"] --> B["为什么跳过 3.0？"]
    A --> C["三大破坏性变更"]
    A --> D["新能力"]
    A --> E["发布纪律"]

    B --> B1["2023 公开承诺：<br/>永不做 htmx 3"]
    B --> B2["fixi.js 实验暴露真相：<br/>XMLHttpRequest 是历史包袱"]
    B2 --> B3["fetch() 重构必然 breaking"]
    B3 --> B4["保住承诺的字面<br/>跳号发布 4.0"]

    C --> C1["继承显式化<br/>属性需加 :inherited 后缀"]
    C --> C2["24个事件改名<br/>htmx:phase:action 语法"]
    C --> C3["删除 localStorage 历史快照<br/>后退 = 重新请求"]

    D --> D1["fetch() 内核 + 流式响应<br/>与 LLM 输出天然契合"]
    D --> D2["idiomorph morph swap 进核心"]
    D --> D3["hx-partial 标签<br/>替代 OOB swap 大部分场景"]
    D --> D4["hx-live 脚本 / htmax.js 打包"]

    E --> E1["htmx 2 永久支持"]
    E --> E2["2027 年初前保持 next tag<br/>绝不强制升级"]
    E --> E3["upgrade-check CLI<br/>+ 4 个 agent skill"]

    D1 --> F["AI 时代结构性优势：<br/>接缝少 / 输出可验证 / 上下文小"]
```

## 实战启示：你现在该怎么选？

把视频的结论压缩成一张决策清单：

**如果你在维护 htmx 2 应用**：什么都不用做，这不是我的建议，是维护者本人的。没有安全悬崖，没有截止日期。跑一遍 `npx htmx.org@4.0.0 upgrade-check` 看看工作量，把真正的迁移排到业务不忙的季度。

**如果你这个月就要上线新项目**：从 2.x 开始——它稳定、生态成熟、永久支持。**如果你的项目年底之后才上线，或者你是去学习的**：直接上 4.0，从第一天就拥有新事件模型、显式继承和原生流式，彻底跳过迁移。两个答案都对，区别只是你对风险的胃口。

**如果你从没碰过 htmx**：成本最低的实验是15分钟——在现有页面加一个 script 标签、在某个按钮上加一个 `hx-get` 属性。如果你的反应是“就这？"，那就是这个设计的精髓；如果你的反应是“我想念我的组件”，那也是完全合法的答案，你只用一个下午就验证完了架构偏好。

**更普适的三条工程启示**：第一，评估依赖时，把“维护者如何对待旧版本”当作比 Star 数更重的指标——htmx 对 1.x 的永久支持是已经兑现过的记录。第二，做技术承诺时留好“字面与精神”的分辨率，htmx 示范了如何用行动而非话术填补两者的缝隙。第三，在 AI 大量生成代码的时代，优先选择“正确性可见”的架构——这条判断的价值已经超出前端范畴。

## 延伸学习路径

1. **《Hypermedia Systems》**（hypermedia.systems）—— Carson Gross 等人写的官方书籍，从 hypermedia 思想史讲到生产实践，是这条路线的圣经。
2. **htmx 官方文集**（htmx.org/essays）—— 重点读 `The fetch()ening`（4.0 的第一手叙事）和 `A Real World React to htmx Port`（67% 代码削减案例的原始出处）。
3. **fixi.js**（github.com/bigskysoftware/fixi）—— 一个下午能读完的极简实现，理解 htmx 本质的最好教材，也是 4.0 的思想原型。
4. **idiomorph**（github.com/bigskysoftware/idiomorph）—— 4.0 进核心的 DOM morphing 算法，同样出自 Carson 之手，Hotwire 也采用了它。
5. **Signal Coders 的 29 分钟版本**（见参考来源4）—— 想要更完整叙事（含 Drupal 细节和 AI 论点展开）的观众，配合本期视频互补观看。

## 一句话总结

**htmx 4.0 证明了这世界上还存在另一种发大版本的方式：不靠加功能收编你，靠删代码和永久支持来兑现承诺——而“完成式软件”不是情怀，是一种可验证的工程纪律。**

## 参考来源

1. [HTMX 4.0 Is Here - And There's No HTMX 3 (Here's Why) — Cloud Codes](https://www.youtube.com/watch?v=qhfgXVVNYL0) — 本文深度解读的核心视频
2. [htmx 4.0.0 has been released! — htmx 官方发布公告（2026-08-28）](https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released) — 正式版变更的第一手来源
3. [HTMX 4.0 Explained: What Breaks, What's Brilliant, and Why There's No HTMX 3 — Signal Coders](https://www.youtube.com/watch?v=PjRMwVmeZ0c) — 29分钟同题深度版，Drupal 与 AI 论点的主要来源
4. [HTMX Explained: The "Dumb" HTML Secret Replacing React — Kai](https://www.youtube.com/watch?v=HPAh1uiE2z0) — hypermedia 核心概念与 67% 代码削减案例
5. [The fetch()ening — Carson Gross 的 4.0 宣告文章（htmx.org/essays）](https://htmx.org/essays/the-fetchening/) — 版本跳号的第一人称解释
6. [Hacker News 首页](https://news.ycombinator.com/) — htmx 4.0.0 发布当日（2026-08-29）位列热榜第二（472 points），交叉验证发布事实

---
> 本文由「51学通信」技术团队出品。51学通信由通信行业18年老兵**爱卫生**（微信ID: gprshome201101）维护，聚焦5G/6G核心网、3GPP标准解读、通信前沿技术深度分析。
> 出版作品有《5G核心网原理与实践》《IMS原理与实践》等4本通信专业书籍。知识星球「51学通信」提供深度技术答疑和行业洞察。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)
