tamnd/kage 源码：https://github.com/tamnd/kage # kage CI (https://github.com/tamnd/kage/actions/workflows/ci.yml) 发布页 (https://github.com/tamnd/kage/releases/latest) Go 参考文档 (https://pkg.go.dev/github.com/tamnd/kage) Go 报告卡 (https://goreportcard.com/report/github.com/tamnd/kage) 许可协议 kage（影，“shadow”）可将网站克隆到本地文件夹中，离线浏览，所有脚本均被移除。它使用真实的无头 Chrome 浏览器打开每个页面，等待页面稳定后，截取用户实际看到的 DOM，然后删除所有 JavaScript，并将 CSS、图片和字体下载到本地路径。最终磁盘上的内容看起来与在线站点一致，但不运行任何代码。 安装 • 快速开始 • 命令 • 克隆 • 打包 • 原生窗口 • 工作原理 kage 克隆 paulgraham.com，打包为一个文件，并在离线状态下提供服务 你一定遇到过这样的问题：点击“另存为”保存了一个想留存的页面，六个月后打开发现一片空白、永不停歇的加载动画，或者一个仍在尝试访问已失效分析服务器的副本。那个页面从来不属于你——它只是别人 JavaScript 的瘦客户端。 kage 选择了另一条路：驱动真实的浏览器，让页面完成所有操作，抓取最终结果，然后从中剥离所有脚本。没有追踪、没有网络请求、没有意外。只有 .html 文件，你可以直接从磁盘打开、传给朋友，或者打包成单个文件保存十年。 完整文档与指南请访问 kage.tamnd.com (https://kage.tamnd.com)。 ## 安装 bash go install github.com/tamnd/kage/cmd/kage@latest 更倾向于预构建的二进制文件？请从 releases (https://github.com/tamnd/kage/releases) 获取压缩包、.deb/.rpm/.apk 安装包或校验和。也可以直接使用容器镜像，其中已捆绑 Chromium，无需自行安装 Chrome： bash docker run --rm -v "$PWD/out:/out" ghcr.io/tamnd/kage clone paulgraham.com kage 需要真实的浏览器，因此主机上必须安装 Chrome 或 Chromium。它会自动检测系统安装位置；可通过 --chrome 或 KAGE_CHROME 环境变量指定具体路径。容器无需额外依赖。 自带 shell 补全功能：kage completion bash|zsh|fish|powershell。 ## 快速开始 让我们镜像 Paul Graham 的随笔，让你在飞机上、无 WiFi 的笔记本电脑上，甚至 2050 年该网站改版后仍能阅读： bash # 1. 克隆网站到 $HOME/data/kage/paulgraham.com/ kage clone paulgraham.com # 2. 离线状态下在浏览器中阅读 kage serve $HOME/data/kage/paulgraham.com # 打开 http://127.0.0.1:8800 这就是完整流程。每一篇随笔、每一张图片、每份样式表，都冻结在你的磁盘上，零网络即可运行。接下来的两个步骤是可选的，但效果很好：将整个内容压缩成一个文件，并在独立窗口中打开。 bash # 3. 将镜像压缩成一个可共享的文件 kage pack paulgraham.com # -> paulgraham.com.zim kage open paulgraham.com.zim # 4. 或者打包成一个本身就是网站的可执行文件 kage pack paulgraham.com --format binary -o paulgraham ./paulgraham # 自启动服务，无需安装任何东西 ## 命令 | 命令 | 功能 | | — | — | | kage clone <url> | 在无头 Chrome 中渲染网站，写入可浏览、无脚本的镜像 | | kage serve [dir] | 通过本地 HTTP 服务器预览克隆的文件夹 | | kage pack <host> | 将镜像压缩为单个 ZIM 存档或自包含的查看器二进制文件 | | kage open <file> | 离线阅读打包后的 ZIM 文件 | ## 克隆 bash # 整个网站，保存到 $HOME/data/kage/<host>/ kage clone https://paulgraham.com # 仅前 50 个页面，深度 2 层，快速体验 kage clone paulgraham.com --max-pages 50 --max-depth 2 # 仅克隆大网站的某个区域 kage clone go.dev --scope-prefix /doc # 同时包含子域名，并滚动页面以触发懒加载图片 kage clone example.com --subdomains --scroll # 下个月回来原地重新渲染，抓取新文章 kage clone paulgraham.com --refresh 克隆过程是一个礼貌的广度优先爬取。它会读取 robots.txt，从 sitemap.xml 中获取种子 URL，并默认只爬取种子主机（除非另行指定）。它还是顽固的幂等操作：每个页面以其写入的文件为键，因此同一篇文章通过 http 和 https（带或不带尾部斜杠）访问时，只会被获取一次。按 Ctrl-C 中断，它会保存当前进度；再次运行时会从中断处继续。--refresh 原地重新渲染，--force 则删除该主机原有内容并重新开始。 你可能会用到的标志： | 标志 | 默认值 | 说明 | |——|———|——| | -o, --out | $HOME/data/kage | 输出根目录；镜像保存到 <out>/<host>/ | | -p, --max-pages | 0 | 最多抓取 N 页（0 表示无限制） | | -d, --max-depth | 0 | 跟随链接的深度（0 表示无限制） | | --scope-prefix | | 仅爬取以此前缀开头的路径 | | --subdomains | false | 将种子主机的子域名纳入范围 | | --exclude | | 要跳过的路径前缀（可重复） | | --scroll | false | 自动滚动每个页面以触发懒加载 | | --workers | 4 | 同时渲染的页面数 | | --no-robots | false | 忽略 robots.txt（请友善使用） | | -f, --force | false | 先删除该主机已有的镜像 | | --chrome | | Chrome/Chromium 二进制文件路径 | kage clone --help 包含更多信息，包括渲染时间、并发和资源大小等参数。 ### 服务 kage serve 运行一个小型静态文件服务器，使克隆文件夹中的链接和资源像在真实主机上一样解析： bash kage serve $HOME/data/kage/paulgraham.com # 打开 http://127.0.0.1:8800 ## 打包为一个文件 镜像是一个文件夹，适合浏览但不便移动。复制成千上万个小文件很慢，“给你这个目录”也不是便捷的分享方式。kage pack 将整个镜像压缩成一个文件，你可以选择两种形状：开放的 ZIM 存档，或一个本身就是站点的可执行文件。 ### 单个 ZIM 文件 bash kage pack paulgraham.com # -> paulgraham.com.zim kage open paulgraham.com.zim ZIM 是一种开放文件格式，专门用于将整个网站（或整个维基百科）压缩为一个索引化的只读文件。kage 将整个镜像写入其中，文本用 zstd 压缩，媒体文件原样存储。它是 Kiwix (https://kiwix.org) 的后台格式——这个离线内容项目让人们在船上、没有网络的教室里、或长途飞行的手机上阅读维基百科、Stack Overflow 和 Project Gutenberg。 由于 ZIM 是标准化格式而非 kage 专有，你今天创建的 paulgraham.com.zim 多年后仍可在任何 ZIM 阅读器中打开。因此你不会被 kage 锁定。kage open 是最快的查看方式，但该文件同样适用于更广泛的 Kiwix 生态系统： bash kage open paulgraham.com.zim # 用 kage 阅读 kiwix-serve paulgraham.com.zim # 或用 Kiwix 在 http://localhost 提供服务 你也可以在 Kiwix 桌面应用 (https://kiwix.org/en/applications/) 中双击打开，或在 Kiwix for Android / iOS (https://kiwix.org/en/applications/) 中加载，从而在手机上阅读你的镜像。 注意：kage 写入的是结构有效且带有标准元数据的存档，但它不会构建 Kiwix 自身打包版本所带的全文搜索索引，因此浏览和点击在所有地方都能正常工作，但阅读器内的搜索功能有限。 打包是确定性的。相同的镜像总是产生字节完全一致的文件，存档 UUID 由内容派生而非随机生成，因此可以安全地进行校验和缓存。裸主机名会解析到默认输出目录，这也是为什么 kage pack paulgraham.com 在 kage clone paulgraham.com 之后能直接工作。 ### 自包含的二进制文件 --format binary 将存档附加到 kage 的副本上，生成一个单一可执行文件，运行时即可离线提供服务。接收者无需安装任何东西：不需要 kage，不需要 ZIM 阅读器，什么都不需要。 bash kage pack paulgraham.com --format binary -o paulgraham ./paulgraham 附加的存档与平台无关；只有基础可执行文件带有架构信息。默认情况下 kage 会附加到自身，因此你会得到一个当前机器的查看器。使用 --base 指定为其他操作系统构建的 kage（可从 releases (https://github.com/tamnd/kage/releases) 获取每个平台的版本），你可以在自己的机器上为其他平台生成查看器。kage 会读取基础可执行文件的头部以确定目标平台，因此 Windows 查看器会自动获得 .exe 文件名： bash # 在 Mac 上构建 Windows 查看器 kage pack paulgraham.com --format binary --base kage-windows-amd64.exe # -> paulgraham.exe 代价是文件大小。二进制文件包含完整的 kage，因此无论镜像多小，大小约为 13 MiB 加上网站内容。如果你只需要内容，ZIM 格式要小巧得多。 ## 真实窗口，而非浏览器标签页 默认情况下，打包后的二进制文件会打开系统浏览器，这意味着网站会像另一个标签页一样出现，带着地址栏，挤在你已经打开的 47 个标签页旁边。使用 webview 标签构建 kage，它会在自己的窗口中打开站点，底层使用操作系统的 WebView（macOS 上为 WKWebView，Windows 上为 WebView2，Linux 上为 WebKitGTK）。Paul Graham 的随笔，离线状态下以类原生应用的形式呈现： paulgraham.com 在原生 kage 窗口中离线服务 bash make build-webview # 或者：CGO_ENABLED=1 go build -tags webview ./cmd/kage kage pack paulgraham.com --format binary --base bin/kage -o paulgraham ./paulgraham # 打开一个窗口，不见浏览器踪影 此构建需要 cgo 并链接平台 WebView，因此为可选加入。默认构建为纯 Go（CGO_ENABLED=0），预构建的发布版二进制文件会打开浏览器，这保持了交叉编译的简洁性。kage open 也支持此标签，因此使用 -tags webview 构建后，它也会在原生窗口中显示 ZIM。 ## 工作原理 种子 URL ─▶ 无头 Chrome ─▶ 最终 DOM ─▶ 剥离 JS ─▶ 本地化资源 ─▶ 磁盘 (渲染) (截屏) (清理) (重写链接) 一个 Chrome 标签页池负责渲染页面；另一个独立的池通过普通 HTTP 获取资源。每个 URL 都确定性地映射到本地路径，因此链接在指向的资源尚未下载完成时就会被重写。输出结构如下： paulgraham.com/ ├── index.html # 主页，脚本已去除 ├── greatwork.html # /greatwork.html，一篇随笔 ├── _kage/ # 保留目录：资源与爬取状态 │ ├── paulgraham.com/site.css # 本地化样式表（url() 已重写） │ ├── paulgraham.com/pg.png │ └── state.json # 已访问集合，用于继续爬取 └── ... pack 也基于同样的理念：镜像中的链接已经是镜像相对路径，这些路径与存档中的内容条目一一对应，因此点击页面中的链接时，无需任何重写即可命中正确的条目。 ## 从源码构建 bash git clone https://github.com/tamnd/kage cd kage make build # -> bin/kage（纯 Go，打开浏览器） make build-webview # -> bin/kage，带原生窗口查看器（需要 cgo） make test # 完整测试套件，包括 Chrome 驱动的端到端测试 make test-short # 跳过需要启动浏览器的测试 仓库按功能模块拆分： cmd/kage/ 薄主入口：固定主线程，然后交给 cli.Execute cli/ cobra 命令树和标志绑定 clone/ 爬取：前沿、渲染工作器、资源工作器、状态恢复 browser/ 无头 Chrome 控制与 DOM 截取 sanitize/ 从 DOM 中移除脚本、事件处理器和 javascript: URL asset/ 下载并本地化 CSS、图片和字体 urlx/ 确定性 URL 到路径映射 zim/ 纯 Go 的 ZIM 读写器 pack/ 将镜像打包为 ZIM 或自包含二进制文件，以及离线 HTTP 处理器 viewer/ 展示服务中的站点：系统浏览器或原生窗口（webview 标签） docs/ tago 文档网站 ## 发布 推送版本标签后，GitHub Actions 会运行 GoReleaser，构建压缩包、.deb/.rpm/.apk 包、带 Chromium 的多架构 GHCR 镜像、校验和、SBOM 和 cosign 签名： bash git tag v0.1.1 git push --tags 镜像标签不带 v 前缀（ghcr.io/tamnd/kage:0.1.1）。Homebrew 和 Scoop 步骤在相应令牌存在前会自动禁用，因此首次发布无需额外密钥即可正常工作。 ## 许可协议 MIT。参见 LICENSE。