如何让一整个网站变成一个可执行文件？kage 自包含离线阅读器打包教程
【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kage
kage 是一个用 Go 编写的离线网站阅读器与镜像打包工具：它能克隆整站并剥离 JavaScript，再通过kage pack --format binary把整个网站打包成一个自包含的可执行文件——发给任何人，双击运行即可离线阅读，无需安装任何依赖。
这篇文章带你走完整条路径：安装 → 克隆整站 → 打包成单个可执行文件，并顺带学会跨平台生成、原生窗口版和常见问题。跟着做大约 5 分钟，你就能得到"一个文件 = 一个网站"的离线阅读器。
一、为什么"另存为"救不了你，而 kage 可以？
用浏览器"另存网页"保存的内容，往往只存下一个空壳：页面依赖的 JavaScript 没保存下来，图片样式可能丢失，半年后打开就是一片空白。
kage 走的是一条完全不同的路线：
- 用真实的无头 Chrome 打开页面，等渲染完成；
- 对"人类看到的样子"做一次快照，然后删掉全部 JavaScript；
- 把 CSS、图片、字体全部下载并改写成本地路径。
最终落盘的是能直接打开的纯.html文件——看起来和真实网站一模一样，却不运行任何代码。克隆完成后，再执行一条pack命令，整个文件夹就能被压进一个可执行文件里。
二、一键安装 kage（三种方式任选）
kage 是单文件 Go 程序，安装极其简单。任选其一：
# 方式 1：go install（需要 Go 环境） go install github.com/tamnd/kage/cmd/kage@latest # 方式 2：Homebrew（macOS） brew install --cask tamnd/tap/kage # 方式 3：Scoop（Windows） scoop install kage💡 kage 会驱动真实浏览器渲染页面，所以系统里需要装有 Chrome 或 Chromium（会自动找到系统安装）。如果你只装了 Docker，也可以直接跑容器镜像：
docker run --rm -v "$PWD/out:/out" ghcr.io/tamnd/kage clone paulgraham.com。
三、核心流程：3 条命令，从网站到可执行文件
整个过程只有三步，以经典的 essays 网站 paulgraham.com 为例。
第 1 步：克隆整站到本地
kage clone paulgraham.com镜像会落在$HOME/data/kage/paulgraham.com/。这一步是个"礼貌的广度优先爬取"：它会读取robots.txt、从sitemap.xml自动发现页面，并且按文件路径去重——同一篇文章不管从 http 还是 https 访问都只抓一次。中途按 Ctrl-C 也会保存进度，下次再跑自动续抓。
常用参数速查：
| 参数 | 作用 |
|---|---|
--max-pages 50 | 最多渲染 50 页，快速试水 |
--max-depth 2 | 链接最多跟 2 层 |
--scope-prefix /doc | 只抓某个子目录 |
--scroll | 自动滚动页面，触发懒加载图片 |
--refresh | 增量刷新，抓到新内容 |
第 2 步：打包成一个可执行文件
kage pack paulgraham.com --format binary -o paulgraham执行完你会得到一个名为paulgraham的文件，终端输出类似：
packed paulgraham size 21.9 MiB run ./paulgraham to view the site offline原理很简单：kage 先把镜像写成一个 ZIM 档案（文本 zstd 压缩、媒体原样存放），再把它追加到一份 kage 自身副本的末尾，并在尾部写上一个KAGEPCK1标记记录档案长度。于是这个可执行文件运行起来就是"自带网站数据的服务端"：它会在本地随机端口启动，自动打开你的浏览器，整站离线可读。这个拼接逻辑就实现在 pack/binary.go 里。
第 3 步：运行，开始离线阅读
./paulgrahamserving offline site at http://127.0.0.1:52431 (Ctrl-C to stop)就这样——一个文件，就是一个网站。把它拷进 U 盘、发到邮箱、丢进网盘，接收方不需要安装 kage、不需要 ZIM 阅读器、甚至不需要联网。
四、进阶技巧：跨平台生成"目标系统"的阅读器
追加到末尾的 ZIM 档案是平台无关的，只有基座可执行文件携带架构信息。所以在 Mac 上也能打包出 Windows 版阅读器：只要把--base指向一个 Windows 版 kage 即可，kage 会读取基座的可执行文件头自动识别目标系统，输出自动带上.exe后缀：
# 在 Mac 上，为 Windows 用户生成阅读器 kage pack paulgraham.com --format binary --base kage-windows-amd64.exe # -> paulgraham.exe三个打包形态怎么选？一张表看懂：
| 形态 | 命令 | 大小 | 适合场景 |
|---|---|---|---|
| ZIM 档案 | kage pack paulgraham.com | 最小（纯内容） | 自己阅读、用 Kiwix 生态打开 |
| 自包含可执行文件 | --format binary | ≈13 MiB + 站点 | 发给"零依赖"的任何人 |
| 双击桌面应用 | --app | ≈13.5 MiB + 站点 | macOS 生成.app，双击即开、无终端、自动用站点 favicon 当图标 |
⚖️ 代价是体积：可执行文件内嵌了完整 kage，所以无论站点多小都在 13 MiB 起步。只关心内容时用 ZIM 更省空间；ZIM 还是开放标准格式（Kiwix 用的就是它），多年后任何 ZIM 阅读器都能打开。
五、终极形态：弹出原生窗口，而不只是浏览器标签页
默认打包出来的阅读器会打开系统浏览器——网站会变成又一个带地址栏的标签页。想让"它就是个 App"的感觉更彻底？用webview编译标签重建 kage，它就会改用操作系统的 WebView（macOS 为 WKWebView、Windows 为 WebView2、Linux 为 WebKitGTK）在独立原生窗口中展示站点：
make build-webview # 或：CGO_ENABLED=1 go build -tags webview ./cmd/kage kage pack paulgraham.com --format binary --base bin/kage -o paulgraham ./paulgraham # 弹出原生窗口，没有浏览器这正是文章开头那张截图的效果：整站离线、独立的窗口、标题栏直接来自档案的标题。
六、常见问题速查
| 问题 | 解决方法 |
|---|---|
| 镜像太大，打包太慢 | 克隆时加--max-pages/--scope-prefix控制范围 |
| macOS 首次运行被 Gatekeeper 拦截 | 执行xattr -d com.apple.quarantine ./paulgraham解除隔离 |
| Windows 上想双击无黑框 | 用 release 里的 GUI 版基座：--base kage-windows-gui-amd64.exe |
| 重新打包时想省时间 | kage pack支持--incremental，只压缩发生变化的数据块 |
七、想看源码？从这里入手
整个"打包成可执行文件"的功能代码量很小，非常适合作为 Go 入门阅读：
- 打包命令与参数解析：cli/pack.go
- 二进制拼接（ZIM 追加 + 尾部标记）：pack/binary.go
- ZIM 读写实现（纯 Go）：zim/writer.go、zim/reader.go
- 离线服务处理：pack/serve.go
- 更多打包细节：docs/content/guides/packing-a-mirror.md
总结：kage clone把网站变成纯静态镜像，kage pack --format binary再把镜像和一个迷你 kage 拼成一个可执行文件。三条命令，一个文件，一个可以随时离线打开的完整网站——这就是把整站塞进一个可执行文件的全部秘密。🚀
【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kage
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
