每个URL如何确定性映射到本地路径？kage资源本地化与链接重写机制源码级解析

每个URL如何确定性映射到本地路径kage资源本地化与链接重写机制源码级解析【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kagekage 是一个网站离线镜像工具它用无头 Chrome 渲染页面把 CSS、图片、字体下载为本地文件并将所有链接重写为本地相对路径。本文从源码层面拆解 kage 的 URL 本地路径映射规则——为什么https://ex.com/docs/永远落成docs/index.htmlhttps://cdn.io/font/x.woff2永远落在_kage/cdn.io/font/x.woff2从而让镜像页面断网双击即可打开。先看落盘效果映射的具体形态kage clone paulgraham.com之后磁盘上的目录长这样paulgraham.com/ ├── index.html # 首页脚本已剥离 ├── greatwork.html # /greatwork.html 文章页 └── _kage/ # 保留目录资源与爬取状态 ├── paulgraham.com/site.css # 本地化的样式表内部 url() 已重写 ├── paulgraham.com/pg.png └── state.json # 已访问集合用于断点续传两条核心规律页面镜像 URL 的路径/docs/intro变成docs/intro/index.html资源统一收进保留目录_kage/host/...与站点自身的路径树永不冲突。保留目录名_kage在 urlx/urlx.go 中定义为DefaultReserved刻意选了一个真实 URL 几乎不会出现的段名。第一步 Normalize把不同写法的 URL 收拢成同一个规范形映射之前先去重。同一条资源可能以HTTPS://Other.COM/Y、https://other.com:443/Y等多种写法出现canonical 会统一协议与 host 转小写丢弃 fragment#frag和默认端口80/443path.Clean清理路径但保留有意义的结尾斜杠/docs/≠/docs查询串做安全转义真实站点会发出a.css?Thursday, 26-Feb-2026 16:26:41 UTC这种带空格的缓存破坏参数safeRawQuery 按 RFC 3986 只编码不合法字符空格变%20而%转义和、等合法子分隔符原样保留——修好请求行的同时盘上的文件键也随之稳定。Normalize 同时拒绝javascript:、mailto:、data:、blob:、纯#锚点等无法抓取/下载的引用原样留在页面上。LocalPath 规则页面镜像 URL 路径资源收进 _kage映射本体是 LocalPath按类型分两条规则页面Pagehttps://ex.com/ → index.html https://ex.com/docs/ → docs/index.html https://ex.com/docs/intro → docs/intro/index.html https://sub.ex.com/x → sub.ex.com/x/index.html两个细节让同一页面只落一份文件成立collapseIndex 把目录索引文档折叠成目录本身/、/index.html、http://与https://写法全部落到同一个index.html子域名页面如开启--subdomains后会多一段 hostsub.ex.com/x落sub.ex.com/x/index.html永远不会与主域的路径树撞车。资源Assethttps://ex.com/css/main.css → _kage/ex.com/css/main.css https://cdn.io/font/x.woff2 → _kage/cdn.io/font/x.woff2 https://ex.com/assets/ → _kage/ex.com/assets/indexsplitAsset 为目录式资源路径以/结尾或空路径补一个index文件名保证落盘永远有扩展名可读。查询串折叠成哈希?qcats这类参数通过 applyQuery 取 SHA-256 前 6 位插到扩展名前https://ex.com/img/logo.png?v3 → _kage/ex.com/img/logo__q-a1b2c3.png https://ex.com/search?qcats → search/index__q-a1b2c3.html同一查询永远得到同一文件稳定哈希不同查询得到不同文件不碰撞——这正是 urlx_test.go 里反复验证的两条断言。Rel 相对重写从页面目录算到目标文件映射出两个绝对相对镜像根路径后Rel 计算从页面所在目录到目标文件的相对链接写回 HTML/CSS页面 docs/intro/index.html → _kage/ex.com/css/main.css 相对链接为 ../../_kage/ex.com/css/main.css → 根 index.html 相对链接为 ../../index.html测试中有一条值得注意的不变式TestRelResolves把页面目录与 Rel 的结果拼起来再清理必然精确落在目标文件上。这条往返可达性质保证了离线时浏览器解析相对链接一定命中正确文件。Sink 回调为什么链接可以先于下载完成被重写这是整个设计里最巧妙的一环。页面渲染完、资源还没下载HTML 里的链接就能先改好——因为双方都对字节最终住在哪里有共识。RefSink 是一个回调函数(URL, 类型) → 写回标记的字符串。cloner.go 中闭包实现它的决策逻辑情况行为写回的内容范围内的页面链接入队待渲染本地相对路径应本地化的资源wantAsset 通过入队待下载本地相对路径站外页面 / 站外资源 / 大体积媒体不动保留原始绝对 URLwantAsset只凭 URL 就能做决策两道闸门注册域检查SameRegistrableDomain 用 eTLD1 判断资源是否站点自己的——developer.apple.com、www.apple.com、images.apple.com都算apple.com的而cdn-apple.com或第三方统计脚本不算默认留在线上扩展名黑名单视频、安装器、压缩包、PDFDefaultSkipAssetExts不下载避免 500 MB 的安装包把镜像撑爆。HTML 侧重写RewriteHTML 遍历 DOM覆盖a/area的 href、img的 src 与 srcset保留宽度/密度描述符、link relstylesheet|icon|preload…、video/audio的 src 与 poster、style内容以及任何元素的行内style。a href还会先经 LikelyPage 判断后缀是.pdf/.png等已知二进制扩展名的当资源下载而非页面渲染。CSS 侧重写RewriteCSS 用正则捕获所有url(...)与import ...含单双引号和无引号形式逐个以样式表自身 URL 为基准解析后交给同一个 sinkdata:内联图跳过。确定性的红利去重、断点续传与单文件打包映射一旦是纯函数下游三件事全部免费获得去重页面和资源都用LocalPath的输出做唯一键pageKey / assetKey。同一条文章经 http 和 https 到达、带不带尾斜杠只抓取一次内容完全相同的页面还会被 writePage 硬链接到首个文件磁盘不重复占字节。断点续传已访问集合写入_kage/state.jsonCtrl-C 退出再运行即从断点继续因为做过什么完全由这些确定性路径刻画。打包零重写kage pack把整个镜像塞进 ZIM 单文件时页面里已是镜像相对路径与归档内容条目一一对应——pack/serve.go 的注释点明点击即命中正确条目回读时不再需要任何重写。阅读源码的快速入口想搞懂看哪里URL 规范形与去重键urlx/urlx.go映射主规则LocalPath、collapseIndex查询串哈希文件名applyQuery相对链接计算Rel 与往返测试HTML/CSS 引用重写asset/html.go、asset/css.go本地化决策与入队cloner.go 的 sink、wantAsset映射的全部期望值urlx_test.go一句话总结先把 URL 规范化成唯一字符串再用纯函数把它映射成磁盘路径链接重写与下载解耦——这就是 kage 的镜像既离线可用、又可去重续传、还能压进一个 ZIM 文件的全部秘密。【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考