Wayback Machine 浏览器扩展 Safari 版全解析：核心功能、版本演进与源码实现

• 前端
• 浏览器控制

导读

本文以 appstores/safari/changelog-safari.md 为主体骨架，系统梳理 Internet Archive 官方 Wayback Machine 浏览器扩展在 Safari 平台上的功能定位与版本迭代脉络（从 2019 年的 1.2.2 一路演进到当前 3.4.x），并结合作品仓库中的 webextension/scripts/background.js、webextension/scripts/utils.js 以及 safari/ 目录下的 Xcode 工程源码，逐项解析快照计数徽章、右键菜单、404 恢复、Save Page Now 等核心能力的底层实现。读完本文，你将完整掌握该扩展在 Safari 上的功能全貌、各版本升级要点，以及这些功能在 Web Extension 架构中是如何落地的。

一、Safari 版扩展的定位与功能全景

1.1 官方扩展的定位

changelog-safari.md 开篇即点明定位：The Internet Archive presents The Official Wayback Machine Extension，即由互联网档案馆（Internet Archive）官方出品的 Wayback Machine 浏览器扩展。借助 Wayback Machine 的时间回溯能力，用户可以"回到过去"，查看一个网站在整个 Web 历史中如何发生变化与演进。该扩展覆盖 Chrome、Firefox、Edge 与 Safari 14+ 四个平台（见 README.md 的安装说明），本仓库中的 safari/Wayback Machine.xcodeproj 即面向 macOS Safari 的工程。

1.2 核心功能清单（原文档 Description）

根据原文档，Safari 版扩展具备以下功能：

这份功能清单在描述层面对应 appstores/description.md 的 "Full Description (Safari only)" 小节；在实现层面，绝大多数能力由 webextension/ 下的共享 Web Extension 代码承担，Safari 工程仅负责壳层桥接（详见本文第四节）。

二、版本历史逐版解读：1.2.2 → 1.4 的关键里程碑

changelog-safari.md 保留了 Safari 版早期（1.x 时代）的完整版本历史，这是理解该扩展演进逻辑的第一手材料。

2.1 1.4（2020 年 3 月 17 日）：徽章计数与右键菜单

该版本新增两个功能：

• 工具栏徽章（badge）：在工具栏按钮上显示"当前访问网站被存储的快照数量"，并在弹出窗口中显示最近一次快照的日期。原文档特别注明：在隐私浏览（Private Browsing）模式下不会激活该功能，以尊重用户隐私。
• 右键菜单 "Open in Wayback Machine"：将鼠标悬停在链接上并右键，即可直接打开该链接在 Wayback Machine 中的存档。

这两个功能的现代实现都能在源码中找到对应物：

• 快照计数徽章由 utils.js 的 getWaybackCount() 与 background.js 的 updateWaybackCountBadge() 配合实现。前者请求hostURL + '__wb/sparkline?collection=web&output=json&url='接口，把返回的years对象展开求和得到快照总数，并附带回first_ts（最早快照时间）与last_ts（最新快照时间）；后者在wm_count_setting开启、URL 合法且未处于保存状态时，调用badgeCountText()将数字格式化为徽章文本（见 utils.js#L302-L314：小于 1000 直接显示，1000～9999 显示一位小数加 K 后缀，小于 100 万显示整数 K，大于等于 100 万显示 M），并将徽章底色设为#9A3B38的红色。
• 右键菜单的现代形态由 utils.js 的 setupContextMenus() 创建，点击处理逻辑在 background.js 的 contextMenus.onClicked 中：first（Oldest Version）打开https://web.archive.org/web/0/、recent（Newest Version）打开https://web.archive.org/web/2/、all（All Versions）打开https://web.archive.org/web/*/，save（Save Page Now）则以capture_all: 1参数触发存档。可见 1.4 时代的单条 "Open in Wayback Machine" 菜单，在后来的 3.x 重做中被细化为 Oldest / Newest / All / Save 四个更精确的菜单项。

2.2 1.3.1（2020 年 2 月 28 日）与 1.3（2020 年 2 月 18 日）：UI 改版与免登录

这两个版本的核心变化一致：

• 全面改版 UI（overhauled the UI）；
• 修复若干 bug；
• 大多数功能无需登录即可使用（most features work without requiring a log in）；
• 对深色模式（Dark Mode）做了适配（Also looks nice now under Dark Mode）。

"免登录使用"这一方向在后续版本中持续深化：3.1 版本实现 "Save Page Now" 无需登录即可存档，仅有部分功能保留登录要求（以图标代替复选框标识，见 appstores/changelog.md）。在源码层面，登录态检测由 utils.js 的 checkAuthentication() 完成——通过chrome.cookies.getAll({ url: 'https://archive.org' })检查logged-in-sig/ia-authcookie，并在 cookie 缺失时尝试从本地存储恢复；savePageNowChecked()（background.js#L42-L46）会先做登录检查再把结果传给savePageNow()，未登录时发送的Accept请求头会切换为text/html形式以兼容匿名存档接口（background.js#L70-L72）。

2.3 1.2.2（2019 年 8 月 18 日）：空白条目

该版本在 changelog 中记录为 "(blank)"，没有留下具体变更说明，从版本号间隔（1.2.2 之后是 1.3）可以推断这是一次维护性发布。原文档如实保留了该条目，本文亦不做臆测性补充。

三、从 1.x 到 3.x：现代版本的演进脉络

changelog-safari.md 截止于 1.4（2020 年 3 月），而仓库中的 appstores/changelog.md 记录了全平台（All Browsers）后续的演进，其中明确标注了 Safari 专属条目。将两份文档拼接起来，可以得到 Safari 版完整的演进时间线：

从工程文件看，当前 Safari 工程版本为3.4.3（safari/Wayback Machine.xcodeproj/project.pbxproj 中MARKETING_VERSION = 3.4.3、CURRENT_PROJECT_VERSION = 23），而共享扩展的 webextension/manifest.json 声明manifest_version: 3、version: "3.4.8"。也就是说，今天的 Safari 版已经是完全重写后的 3.x 架构，1.x 时期的版本历史属于该产品在旧 Safari App Extension 体系下的早期形态。

四、Safari 平台的工程实现细节

4.1 壳层应用与扩展的双 Target 结构

仓库的 safari/ 目录包含两个 Target：

• Wayback Machine（壳层 App）：提供安装引导窗口。其 ViewController.swift 通过SFSafariExtensionManager.getStateOfSafariExtension(withIdentifier:)查询扩展启用状态，在状态标签上显示 "Extension is On / Extension is Off"，并提供按钮调用SFSafariApplication.showPreferencesForExtension(withIdentifier:)直接打开 Safari 的扩展偏好设置；AppDelegate.swift 在 Help 菜单中提供打开支持网站的动作。
• Wayback Machine Extension（扩展本体）：核心类为 SafariWebExtensionHandler.swift，实现NSExtensionRequestHandling协议，在beginRequest(with:)中接收来自browser.runtime.sendNativeMessage的消息并回包，是 Web Extension 与原生壳层之间的消息桥。

扩展的 Info.plist（safari/Wayback Machine Extension/Info.plist）中，NSExtensionPointIdentifier被设为com.apple.Safari.web-extension，NSExtensionPrincipalClass指向SafariWebExtensionHandler——这正是 Safari 14 识别 Web Extension 扩展点的标准声明方式。此外 safari/Wayback Machine/Wayback_Machine.entitlements 开启了 App Sandbox 与files.user-selected.read-only文件访问权限。

4.2 共享 Web Extension 代码如何工作

Safari 版与 Chrome/Firefox/Edge 版共享 webextension/ 下的全部功能代码。几个关键能力的实现路径如下：

• 404 自动恢复：chrome.webRequest.onCompleted监听主框架加载，凡statusCode >= 400的响应都会把状态与 URL 写入 tab 数据（background.js#L460-L479）；随后checkNotFound()在not_found_setting开启时调用wmAvailabilityCheck()（utils.js#L363-L379，请求wayback/available接口）查询存档是否存在，存在则把工具栏图标切换为 "V" 状态，并视embed_popup_setting决定是否向页面注入 scripts/archive.js 显示横幅（background.js#L484-L527）。
• Save Page Now：savePageNow()（background.js#L56-L131）POST 到hostURL + 'save/'，拿到job_id后再经savePageStatus()轮询save/status/{jobId}接口（依据Retry-After响应头决定重试间隔，background.js#L150-L190），成功后更新徽章计数并发送 "check" 状态图标。
• 相关资源检索：针对 Wikipedia 的书籍/论文、Amazon 图书、TV News 片段等，通过带内存缓存与 10 秒超时的fetchCachedAPI()（background.js#L302-L364）调用services/context/*系列接口，命中后工具栏显示 "R" 状态。
• URL 排除规则：为保护隐私，utils.js 的 excluded_urls 明确排除了localhost、内网地址、chrome:/about:/moz-extension:等内部协议，这与原文档 1.4 中"隐私浏览下不激活徽章"的隐私取向一脉相承。

注意：不同浏览器会使用不同的 API 域名前缀（如 Safari 使用https://safari-api.archive.org/，见 utils.js#L77-L86），因此从源码结构看，Safari 版的 API 流量是与其他浏览器隔离的。

4.3 从源码构建与提交 App Store

仓库内 appstores/safari/README.md 记录了维护者的提交备忘录，可作为实操参考：

• Bundle ID：archive.org.waybackmachine.mac与archive.org.waybackmachine.mac.extension，两个 Target 需保持一致；
• 签名配置：在 "Signing & Capabilities" 中勾选 Automatically manage signing，Team 为 Internet Archive，签名证书为 Development；App Sandbox 不勾选额外项，File Access 保持默认 'none'；
• 构建上传：先在 App Store Connect 添加新版本，然后通过 Xcode 菜单Product > Archive，在 Organizer 中点击 "Distribute App"；
• 导出合规：在 App Store Connect 选择构建版本时，Export Compliance Information 需声明 Uses Encryption = YES、Qualify for Exemption = YES，并确认"None of the algorithms mentioned above"。

普通用户无需源码构建，直接在 Safari 中安装 App Store 版本即可；开发者在 macOS Safari 14+ 上调试本地构建时，需要先在系统设置中开启 "Allow Unsigned Extensions"，再用 Xcode 打开 safari/Wayback Machine.xcodeproj 运行（详见 README.md）。

五、结语

通过 changelog-safari.md 这扇"历史窗口"，可以看到 Safari 版 Wayback Machine 扩展清晰的产品演进脉络：从 2019 年 1.2.2 的起步，到 1.3/1.3.1 确立"免登录 + 深色模式"的使用体验，再到 1.4 引入快照计数徽章与右键菜单，最终在 3.x 时代完成架构级重写并随 Manifest v3 迁移至现代 Web Extension 体系。这份演进史并非孤立的发布记录——工具栏徽章的计数逻辑、右键菜单的 URL 构造、404 恢复的监听链路，至今仍可在 background.js 与 utils.js 中找到一一对应的实现。对于希望理解"浏览器扩展如何与 Wayback Machine API 协同工作"的开发者而言，这份 changelog 加上仓库源码，就是一份可以直接阅读的实战教材。

• 前端
• 浏览器控制