引言：HTML 归档的三难困境
在 Web 内容长期保存的实践中，开发者面临一个经典的三难困境：静态性（自包含所有资源）、单文件性（磁盘存储为单一文件）和高效性（按需懒加载资源）三者难以兼得。传统方案如 MHTML 或 SingleFile 实现了静态与单文件，但强制用户下载全部内联资源；而 WARC/WACZ 格式虽支持高效懒加载，却依赖专门的播放工具，无法直接在浏览器中打开。Gwtar（发音如 “guitar”，扩展名为 .gwtar.html）正是为解决这一困境而生的新型 “多语言” 格式，它巧妙地将 HTML/JavaScript 头部与标准的 tar 归档拼接，通过 HTTP 范围请求实现资源的流式解析与按需加载。
格式解剖：头部、负载与偏移量计算
Gwtar 文件在物理上是一个连续的字节流，其结构可划分为三个逻辑部分：HTML 头部、JavaScript 运行时与 tar 归档负载。头部是一个合法的 HTML 文档，包含必要的 <html>、<head> 和 <body> 标签，并在 <script> 标签内嵌入了关键的运行时逻辑。紧接着头部的是整个格式的核心 —— 一个未经压缩的原始 tar 归档。tar 格式的线性特性在此发挥了关键作用：每个文件条目由 512 字节的头部（包含文件名、文件大小等元数据）和紧随其后的文件内容组成，内容尾部用空字节填充至 512 字节的整数倍。
这种线性结构使得精确计算任意资源在文件中的字节偏移量成为可能。构建工具在打包时会生成一个内嵌的 JSON 清单，记录每个 tar 条目（包括原始 HTML 页面和所有静态资源）的文件大小、内容类型、基准名和 SHA-256 哈希值。更重要的是，工具会根据头部长度、每个 tar 条目的头部大小及填充字节，预先计算出每个资源内容在文件中的起始和结束偏移量。这些偏移量信息被硬编码到 JavaScript 运行时中，为后续的按需范围请求提供了精确的 “地图”。
流式解析：window.stop () 与浏览器控制流
当浏览器开始加载一个 .gwtar.html 文件时，其内置的 HTML 解析器会像处理普通网页一样解析文件头部。关键转折点发生在 JavaScript 调用 window.stop() 的时刻。根据 MDN 文档，此方法 “停止当前浏览上下文中进一步的资源加载，相当于点击了浏览器的停止按钮”。在 Gwtar 的实现中，这一调用被精心安排在 HTML 头部解析完成之后、tar 归档数据开始之前。
window.stop() 的执行有效地中断了浏览器对剩余响应体的自动流式读取，防止了数兆甚至数百兆字节的 tar 数据被一次性下载到内存中。此时，JavaScript 运行时已经就绪，它通过一个 HTTP 范围请求（Range: bytes=start-end）仅获取 tar 归档中的第一个条目 —— 即原始的、未内联的 HTML 文档。获取到的 HTML 片段随后通过 document.write() 或 srcdoc 属性注入到当前文档中，替换掉原先的占位内容。至此，用户看到了页面的真实结构，但所有外部资源（图片、样式表、脚本）的引用仍然是 “断裂” 的。
懒加载实现：请求拦截与范围请求转换
为了实现资源的按需加载，Gwtar 采用了一种 “欲擒故纵” 的策略。在打包阶段，原始 HTML 中所有外部资源的 URL 都被系统地重写为注定会失败的地址，例如指向 http://localhost/ 或一个不存在的路径。当浏览器解析新注入的 HTML 并尝试加载这些资源时，请求会立即失败（产生 404 错误或网络错误）。
JavaScript 运行时通过重写 fetch API、拦截 XMLHttpRequest 或监听 img、link、script 等元素的 error 事件，捕获这些失败请求。捕获到请求后，运行时根据请求的 URL 映射到之前计算好的资源偏移量，然后向同一个 .gwtar.html 文件发起一个新的 HTTP 范围请求，精确请求该资源对应的字节区间。服务器响应 HTTP 206（部分内容）状态码及请求的字节块。最后，运行时将获取到的二进制数据转换为 Blob 或 ObjectURL，并将其赋值给对应的 DOM 元素，完成资源的加载与渲染。
整个过程对用户透明，页面像是正常加载了所有资源，而从网络层面看，浏览器只是在按需读取同一个大文件的不同片段。正如 Gwtar 文档所述，“从页面的角度看，它像是正常的资源加载；从网络的角度看，它只是一系列对同一文件的小范围读取”。
工程实践：打包顺序、MIME 类型与本地限制
在实际部署 Gwtar 时，有几个工程细节至关重要。首先是打包顺序的优化。由于 tar 是线性存储，将关键路径资源（如首屏 HTML、关键 CSS、渲染阻塞的 JS）放在归档的前部，可以确保即使在没有范围请求支持的降级情况下（如 JS 被禁用），浏览器也能优先接收到这些内容，提升感知性能。
其次是应对内容交付网络（CDN）和代理的干扰。某些 CDN（如 Cloudflare）会对 text/html 类型的响应特殊处理，可能剥离 Range 请求头，破坏 Gwtar 的懒加载机制。为此，Gwtar 建议使用自定义的 MIME 类型 x-gwtar 来服务文件。现代浏览器具备内容嗅探能力，即使收到非常规的 MIME 类型，只要文件以 <html> 标签开头，仍会将其作为 HTML 渲染。而 CDN 则因不认识此类型而选择透传请求，从而保留了范围请求功能。
最大的实践限制来自于本地文件系统。当通过 file:// 协议直接打开 .gwtar.html 文件时，浏览器的安全策略（同源策略、CORS）会阻止页面向自身发起 HTTP 请求（即使是范围请求），导致整个机制失效。因此，Gwtar 主要适用于通过 HTTP/HTTPS 协议提供服务的场景。对于本地归档，需要先通过简单命令（如 cat file.gwtar.html | perl -ne'print $_ if $x; $x=1 if /<!-- GWTAR END/' | tar xf -）解包为普通的多文件格式后再浏览。
性能考量：预取、压缩与缓存策略
尽管 Gwtar 的核心是懒加载，但在性能优化上仍有文章可做。对于某些高概率访问的资源（如首图、Logo），运行时可以在页面加载初期就发起预取的范围请求，减少用户交互后的等待时间。同时，需要谨慎处理 JavaScript 资源的加载顺序。由于内联脚本可能依赖于外部库，Gwtar 当前的实现会选择在渲染页面主体前，主动加载所有被引用的外部 JS 文件，以避免执行时依赖未就绪的竞态条件。
在压缩方面，Gwtar 格式本身不进行压缩，这有利于范围请求的精确寻址。然而，这并不妨碍在传输层应用压缩。服务器可以对整个 .gwtar.html 文件启用 gzip 或 Brotli 压缩。不过这里存在一个微妙之处：HTTP 范围请求通常作用于压缩后的字节流。这意味着客户端请求的 start-end 范围是针对压缩后文件的，而运行时计算的偏移量是基于原始未压缩文件的。因此，如果启用传输层压缩，构建工具和服务器必须协调一致，确保偏移量计算的基准统一，或者索性在构建阶段完成资源压缩并计入偏移量计算。
缓存策略同样重要。由于所有资源都来自同一个 URL，标准的 HTTP 缓存头（如 ETag、Last-Modified）将作用于整个文件。一旦文件有任何更新，即使只是修改了一个图片，整个文件的 ETag 都会改变，导致客户端重新下载整个归档（尽管实际可能只请求了其中几个范围）。更精细的缓存可能需要依赖 Service Worker，在客户端根据资源的哈希值建立独立的缓存条目。
结论：Web 归档的新范式
Gwtar 格式的出现，为静态 Web 内容归档提供了一种新颖而实用的解决方案。它巧妙地利用了已有且广泛支持的 Web 标准 ——HTTP 范围请求和 tar 格式，通过前端的 JavaScript 胶水代码将它们串联起来，实现了单文件、自包含且支持懒加载的理想特性。它特别适合用于归档包含大量媒体资源（如图片集、视频、音频讲座）的复杂页面，在保证内容完整性的同时，极大减轻了用户首次访问的带宽负担。
虽然存在本地浏览限制和依赖 JavaScript 的缺点，但其优雅的降级方案（完整下载后仍可视为一个大的内联 HTML 文件）保证了内容的可访问性。对于需要长期保存且希望保持高度可移植性的 Web 内容，Gwtar 代表了一种值得关注的工程实践方向，它证明了通过巧妙的组合与设计，我们依然可以在 Web 的约束下突破看似固有限制，创造出更优的解决方案。
资料来源
- Gwern.net. Gwtar: a static efficient single-file HTML format. https://gwern.net/gwtar
- Hacker News. Gwtar: A static efficient single-file HTML format. https://news.ycombinator.com/item?id=47024506
- MDN Web Docs. HTTP range requests. https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Range_requests