htmx 4.0 发布：基于 Fetch API 重写与显式属性继承规则带来重大升级挑战

一句话结论

htmx 4.0 完成底层架构重写并强制要求显式属性继承，开发者升级时需警惕隐式失效风险。

关键要点

• 传输层从 XMLHttpRequest 彻底替换为原生 fetch() API，支持流式传输且脚本体积控制在约 14KB。
• 属性继承机制改为显式声明，必须在属性名后添加 :inherited 后缀，否则父级属性不会传递给子元素。
• 内置基于 idiomorph 的 Morphing Swap 功能，DOM 更新时能保留输入框焦点等状态，新增 hx-partial 标签优化多目标更新。
• 事件命名规范统一为 htmx:phase:action 格式（如 htmx:after:request），历史记录不再使用 localStorage 保存 DOM 快照。
• 官方提供 npx htmx.org@4.0.0 upgrade-check 命令行工具，用于自动识别属性继承错误及旧版事件名称兼容性问题。

背景与事实

htmx 团队正式发布了超媒体库 htmx 4.0.0 版本。这是继 2024 年 htmx 2.0 发布以来首个主版本更新，新版本历经八个月开发周期，直接跳过了 3.0 版本。htmx 创始人 Carson Gross 曾承诺“永远不会有 htmx 3.0”，当 InfoWorld 询问此次版本跨越原因时，他仅用“Oops”一词概括。这一版本号跳跃并非技术故障，而是对底层传输机制彻底重构的标记。

此次更新的核心在于将长期使用的 XMLHttpRequest 传输机制完全替换为现代 fetch() API。这一改动不仅实现了原生流式传输支持，还成功将脚本体积控制在约 14KB。对于大多数已习惯 htmx 的开发者而言，hx-get 和 hx-post 等核心属性保持原有行为，无需修改基本用法。然而，这一底层重写为两项高价值功能奠定了基础：一是基于 idiomorph 实现的内置 Morphing Swap，解决了传统替换整个 DOM 节点导致输入焦点丢失的问题；二是新增 hx-partial 标签，允许单个响应简洁地更新多个目标元素，为带外交换（OOB Swap）提供了更整洁的实现路径。

除了功能增强，属性继承规则发生了根本性变化。旧版本中，部分属性默认可从父元素继承至子元素，而 htmx 4.0 采用显式机制，只有在属性名后添加 :inherited 后缀时，继承才会发生。DEV Community 上的技术文章特别警告，这是升级过程中最容易导致隐蔽故障的地方。例如，原本通过 hx-headers 向子元素传递 CSRF Token 的实现，若未手动添加 :inherited 后缀，将悄无声息地失效。服务器随后会以 403 状态码拒绝请求，代码表面看似正常，实际业务逻辑已中断。此外，事件名称统一调整为 htmx:phase:action 格式，如 htmx:afterRequest 变更为 htmx:after:request。历史记录机制也得到优化，不再将 DOM 快照保存到 localStorage，而是通过重新获取页面来恢复历史，从而避免干扰第三方脚本。

影响分析

对于中文开发者群体而言，htmx 4.0 的发布意味着使用 Django、Go、Rails 等服务端渲染技术栈的项目面临显著的迁移成本。虽然官方提供了 upgrade-check 命令行工具来辅助识别属性继承问题和事件重命名，但 403 错误等隐蔽故障仍需开发者手动审查核心认证流程。明确属性继承规则虽然在长期可维护性上有所提升，但在短期内增加了代码量，特别是在处理嵌套表单和头部信息传递时。对于采用 AI 辅助开发的团队，由于 htmx 技术栈在 Go、SQLite 等新兴全栈组合中受到 AI 助手的良好支持，开发者可以借助 LLM 快速生成带有 :inherited 后缀的正确代码。然而，对于已有庞大代码库的传统项目，盲目升级至 4.0 版本可能引入难以追踪的逻辑缺陷，建议先在测试环境中利用官方工具进行全量扫描。

适用边界

该结论主要适用于从 htmx 2.x 或早期版本升级至 4.0 的 Web 项目，以及新启动且追求极致轻量级的服务端渲染应用。不适用的场景包括：严格依赖 localStorage 进行前端状态持久化的系统，因为 htmx 4.0 不再向其中写入 DOM 快照；以及希望保持完全向后兼容、不愿处理属性显式继承声明的遗留单体应用。此外，若项目对浏览器 fetch API 的兼容性要求极高，或团队拒绝调整事件监听代码以适配新的命名规范，则暂不建议立即全面迁移，应等待 2.x 版本的长期支持周期结束。

孤本观察

htmx 4.0 通过 npm next 标签发布而非 latest，且承诺 2.x 版本持续支持无终止时间，表明团队在激进重构与用户安全之间寻求了平衡。编辑判断认为，这种“双轨制”发布策略实际上降低了社区迁移的心理门槛，使得开发者可以分批次完成代码适配，而非被迫一次性重构整个前端层。

来源：InfoQ 中文 AI