tamnd/kage · 上手攻略
- 仓库：tamnd/kage
- 链接：https://github.com/tamnd/kage
- 分类：web-archive / offline-tools
- 作者：Tom
- 更新：2026-07-28
这是什么
kage（日语「影」，意为 shadow）是一个用 Go 编写的网站离线镜像工具。它的核心思路与浏览器「另存为」截然不同：用真实 headless Chrome 渲染完整页面，等待 JavaScript 执行完毕并内容稳定后，捕获最终 DOM，剔除所有脚本，最后将 CSS、图片、字体下载到本地并重写引用路径。最终产出是一组纯静态的 .html 文件——完全可离线打开、没有任何追踪或网络请求、开箱即用。
kage 还提供 pack 命令，可将整个镜像压缩成 ZIM 格式（Kiwix 离线阅读器标准格式）或单文件自包含可执行程序，甚至生成双击即开的原生桌面应用。
解决什么问题
传统的「网页另存为」存在致命缺陷：六个月后打开往往是空白页、死循环 spinner，或者页面仍在向后端服务器发请求。JavaScript 驱动的单页应用（SPA）尤甚——保存下来的 HTML 只是一个空壳骨架。
kage 的解决思路：用浏览器真正渲染一遍，拿到最终用户看到的内容，然后彻底去掉代码本身。结果是零依赖的静态快照，任何时候打开都和保存当天完全一致。
快速安装
方式一：Go 安装（推荐，有 Go 1.21+ 环境）
go install github.com/tamnd/kage/cmd/kage@latest
方式二：包管理器
macOS（Homebrew）
brew install --cask tamnd/tap/kage
Windows（Scoop）
scoop bucket add tamnd https://github.com/tamnd/scoop-bucket
scoop install kage
Debian / Ubuntu
curl -fsSL https://tamnd.github.io/linux-repo/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/tamnd.gpg
echo "deb [signed-by=/usr/share/keyrings/tamnd.gpg] https://tamnd.github.io/linux-repo/apt stable main" | sudo tee /etc/apt/sources.list.d/tamnd.list
sudo apt update && sudo apt install kage
Fedora / RHEL
sudo dnf config-manager --add-repo https://tamnd.github.io/linux-repo/dnf/tamnd.repo
sudo dnf install kage
方式三：Docker（无需预装 Chrome）
docker run --rm -v "$PWD/out:/out" ghcr.io/tamnd/kage clone paulgraham.com
方式四：直接下载预编译二进制
访问 https://github.com/tamnd/kage/releases 获取 .deb、.rpm、.apk 或纯二进制压缩包（v0.3.10 为写稿时最新版本，具体以 releases 页为准）。
前置依赖
kage 依赖 Chrome 或 Chromium。工具会自动查找系统安装，或通过 --chrome /path/to/chrome 或 KAGE_CHROME 环境变量指定路径。Docker 镜像自带 Chromium，无需额外安装。
核心用法
基本工作流
# 1. 克隆网站到 $HOME/data/kage/<host>/
kage clone paulgraham.com
# 2. 本地预览（默认端口 8800）
kage serve $HOME/data/kage/paulgraham.com
# 然后浏览器打开 http://127.0.0.1:8800
# 3. 可选：将镜像压缩成单文件
kage pack paulgraham.com # -> paulgraham.com.zim（ZIM 格式）
kage open paulgraham.com.zim # 用 kage 读取 ZIM
# 4. 可选：打包成自运行可执行文件
kage pack paulgraham.com --format binary -o paulgraham
./paulgraham # 双击即开，无需任何依赖
常用参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-o, --out |
$HOME/data/kage |
输出根目录 |
-p, --max-pages |
0（无限制） |
最多抓取页数 |
-d, --max-depth |
0（无限制） |
链接追踪深度 |
--scope-prefix |
— | 只抓取特定路径前缀 |
--subdomains |
false |
是否包含子域名 |
--scroll |
false |
自动滚动触发懒加载图片 |
-f, --force |
false |
先删除现有镜像再重新抓取 |
--refresh |
— | 增量更新（保留已有页面） |
--exclude |
— | 排除的路径前缀（可重复） |
--workers |
4 |
并发渲染页数 |
# 示例：只抓前 50 页，深两层链接
kage clone paulgraham.com --max-pages 50 --max-depth 2
# 示例：抓 go.dev 的 /doc 路径
kage clone go.dev --scope-prefix /doc
# 示例：包含子域名，并触发懒加载
kage clone example.com --subdomains --scroll
# 示例：增量更新已有镜像
kage clone paulgraham.com --refresh
pack 格式选择
ZIM 格式：开放标准（Kiwix 生态），压缩率高，产物体积小，兼容任何 ZIM 阅读器。
kage pack paulgraham.com
# -> paulgraham.com.zim，可用 Kiwix 软件打开
自运行二进制：将 ZIM 附加到 kage 自身，生成单 .exe/二进制文件。
# 在 macOS 上构建 Windows 无控制台窗口的可执行文件
kage pack paulgraham.com --format binary --base kage-windows-gui-amd64.exe -o paulgraham.exe
原生桌面 App：生成 .app（macOS）、.AppImage（Linux）或 GUI 版 .exe（Windows），双击直接打开原生窗口而非浏览器标签页。
# 构建 WebView 原生窗口版（需 cgo + WebView 库）
make build-webview # CGO_ENABLED=1 go build -tags webview ./cmd/kage
kage pack paulgraham.com --format binary --base bin/kage -o paulgraham
./paulgraham # 打开原生窗口，无浏览器痕迹
serve 本地预览
kage serve $HOME/data/kage/paulgraham.com
# 默认监听 http://127.0.0.1:8800
# 支持传入目录路径
典型适用场景
- 学术资料存档：论文网站、参考指南、文档站点，打包后可离线阅读多年
- 出行准备：将目的地旅游页面、地图服务、攻略站点镜像，随身携带无网也能看
- 长期归档：某些博客、论坛有生之年内容，防止网站关停后资料消失
- 内网部署：公司内部 Wiki、文档服务器无法上外网时，提供离线版本
- 隐私离线阅读：完全去除追踪脚本、Analytics，不联网也能安心阅读
坑与注意
- Chrome 依赖：宿主机必须安装 Chrome/Chromium，自动找不到时用
KAGE_CHROME环境变量指定路径。Docker 版自带，无需操心。 - SPA 抓取深度：深度 JavaScript 渲染的 SPA 建议加
--scroll触发懒加载，否则可能丢失内容。 - robots.txt 遵守：默认遵守 robots.txt，用
--no-robots可跳过（不推荐），--crawl-delay可覆盖抓取间隔。 - 中断安全：Ctrl-C 中断时会保存进度，下次运行会自动续抓。
- ZIM 格式搜索：kage 打包的 ZIM 不含全文索引，因此 Kiwix 内搜索功能可能受限，但浏览和链接跳转完全正常。
- 自运行二进制体积：加上 kage 自身（约 13 MiB），二进制模式最小也有 13 MiB+，比纯 ZIM 大得多，仅当你需要零依赖分发时才合算。
- 跨平台构建基础二进制：需要
--base参数指定目标平台 kage 二进制，仅结构头部被读取判断目标系统。
与同类对比
| 工具 | 渲染方式 | JS 处理 | 输出格式 | 依赖 |
|---|---|---|---|---|
| kage | 真实 Chrome | 完全剔除 | HTML/ZIM/二进制/app | Go + Chrome |
| wget | HTTP 下载 | 不处理 | HTML（可能失效） | 无特殊依赖 |
| HTTrack | 爬虫 | 不处理 | HTML | C |
| Monolith（Node） | 无头浏览器 | 可选保留/剔除 | 单 HTML | Node.js |
| Wayback Machine | 服务端渲染 | — | 存档快照 | 无（在线） |
kage 的核心竞争力是真实渲染 + 彻底去 JS，结果是真正长期可用的离线快照，不像 wget/HTTrack 那样拿到的可能是空壳。
一句话推荐结论
需要长期可靠地保存任意网站供离线使用，kage 是目前最省心的方案——真实渲染保证内容完整，剔除脚本保证安全和稳定，一套命令从抓取到打包分发全搞定。