企业官网建设流程全解析

Voyager Safari 插件迁移指南：从「Gemini Voyager」平稳过渡到「Voyager」的完整实操方案

【免费下载链接】voyagerEnhancement suite for Gemini, AI Studio, Claude & ChatGPT — plus a prompt manager for any websites, DeepSeek Harness included. / 面向 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件；其中的提示词管理器可用于任意网站，如 DeepSeek Harness。项目地址: https://gitcode.com/gh_mirrors/ge/voyager

从v1.6.0起，Voyager 的 Safari 宿主 App 由「Gemini Voyager」正式更名为「Voyager」。由于 macOS 按 App 名称识别程序，直接安装新版本会导致新旧 App 并存，进而出现 Safari 扩展重复或行为混乱的问题。本文基于仓库官方文档 docs/fr/guide/safari-migration.md（对应中文版 docs/guide/safari-migration.md），结合 Voyager/App/AppDelegate.swift 等源码实现，完整讲解这次一次性手动迁移的操作步骤、注意事项，以及迁移后由 Sparkle 接管自动更新的底层机制。

为什么要做这次迁移

Voyager 的 Safari 版本由两部分组成：宿主 App（位于/Applications）与 Safari 扩展（Web Extension，由宿主 App 托管）。

• 在v1.6.0 之前，宿主 App 名称为「Gemini Voyager.app」；
• 从v1.6.0 起，宿主 App 更名为「Voyager.app」。

macOS 以 App 名称作为标识。如果你在安装了旧版的前提下直接打开新版 DMG 拖入 Applications，新 App 不会覆盖旧的「Gemini Voyager.app」，而是与它并存在应用程序文件夹中。由于 Safari 扩展由宿主 App 提供，两个 App 同时存在时，Safari 中会出现重复的扩展条目，或出现行为混乱、消息路由不明确等问题。

因此官方在文档中明确标注这是一次需要手动完成一次的迁移操作（原文以 warning 提示块强调）。完成这一次替换之后，后续版本更新即可回归正常的自动更新流程，无需再手动干预。

你的数据不会丢

迁移最令人担心的往往是数据丢失，官方文档对此有明确承诺：

App 的Bundle ID 没有改变，文件夹、灵感库（prompt library）、云同步和所有设置都会保留。这一步只是替换 App 本体，不碰数据。

仓库源码印证了这一点：在 Voyager/Voyager.xcodeproj/project.pbxproj 中，App 与 Extension 的PRODUCT_BUNDLE_IDENTIFIER分别为com.yourCompany.Gemini-Voyager与com.yourCompany.Gemini-Voyager.Extension，此次更名只改了显示名称（INFOPLIST_KEY_CFBundleDisplayName = Voyager），没有改动 Bundle ID。

更名过程中的数据兼容性也在代码层面做了专门处理。例如云盘同步目录标识在 Voyager/Shared/NativeSupport.swift 中定义了新旧两套名称：

enum VoyagerGoogleDriveFolderIdentity { static let currentName = "Voyager Data" static let legacyName = "Gemini Voyager Data" static let markerKey = "voyagerDataFolder" static let markerValue = "1" }

并在 Voyager/Tests/NativeSupportTests.swift 中通过测试保证：只有存在唯一、无歧义的旧名称目录时才执行自动迁移，如果新名称目录已存在则不会覆盖。可见更名迁移是整套设计的一部分，用户的文件夹、提示词库、云同步与设置均被完整保留。

迁移步骤（四步完成）

官方文档给出的操作流程非常简洁，共四步：

1. 完全退出 Safari：在 Safari 中按下⌘Q真正退出，而不是只关闭窗口。这一步很关键，因为 Safari 在运行期间会锁定正在使用的扩展，不彻底退出会导致后续替换不干净。

2. 删除旧 App：打开「访达 → 应用程序」（Finder → Applications），把旧的「Gemini Voyager.app」拖入废纸篓。

3. 安装新 App：打开新下载的 DMG，把其中的「Voyager.app」拖进「应用程序」文件夹。

4. 重新启用扩展：重新打开 Safari →「设置 → 扩展」（Settings → Extensions），勾选启用「Voyager Extension」。

完成以上四步后，迁移即告结束。

应用自身的兜底提醒

值得一提的是，新版 App 本身也内置了对这次迁移的兜底检测逻辑。在 Voyager/App/AppDelegate.swift 中：

• legacyAppPath = "/Applications/Gemini Voyager.app"指向旧 App 的固定路径；
• applicationDidFinishLaunching在启动后延迟 1 秒调用promptLegacyAppRemovalIfNeeded()；
• 该函数通过FileManager.default.fileExists(atPath:)检查旧 App 是否仍存在，若存在则弹出提示框，提供三个按钮：「Move Old App to Trash」（直接调用NSWorkspace.shared.recycle将旧 App 移入废纸篓）、「Migration Guide」（打开迁移指南页面）、「Not Now」（暂不处理）。

同时源码还做了一个细节处理：当本次启动属于后台通知或 URL 回调的静默唤醒（launchedForHandoff）时，不会弹出这个提示框，避免打扰用户的后台操作。这意味着即使你忘了手动删除旧 App，新版本在下次正常启动时也会主动提醒你，且该提醒在旧 App 被删除后便不再出现（源码注释中称为 "self-resolves"）。

两个千万别做

官方文档专门列出了两个容易犯的错误：

• ❌不要同时保留两个 App。旧的「Gemini Voyager.app」如果不删除，两个扩展会在 Safari 中同时生效、互相冲突，行为不可预期。正确做法是像第 2 步那样把旧 App 直接拖进废纸篓。
• ❌不要在 Safari 的「扩展」面板中对旧扩展点击「卸载」（Uninstall）。这个操作会指回旧 App 所在的目录，反而让事情变得更混乱（甚至可能误伤新安装的 App）。正确做法依旧是直接把旧 App 拖进废纸篓。

迁移之后：Sparkle 自动更新接管

完成这次一次性替换后，未来的 Safari 版本更新将通过 App 内置的Sparkle自动更新框架完成，不再需要手动更换 App。

仓库中的相关配置清晰地展示了这条更新链路：

• Voyager/App/Info.plist 中声明了 Sparkle 所需的全部键值：
  • SUAutomaticallyUpdate与SUEnableAutomaticChecks均为true，表示自动检查并自动下载更新；
  • SUEnableInstallerLauncherService为true，允许通过安装器服务完成替换安装；
  • SUFeedURL指向 appcast 订阅源（仓库的 releases 更新流）；
  • SUPublicEDKey为公开 EdDSA 密钥，用于校验更新包的签名；
• Voyager/App/AppDelegate.swift 中通过SPUStandardUpdaterController(startingUpdater: true, ...)在启动时初始化更新器，并在「应用菜单」中插入了「Check for Updates…」菜单项，用户也可随时手动检查更新；
• scripts/generate-sparkle-appcast.sh 展示了发布侧如何用generate_appcast生成带sparkle:edSignature=签名的 appcast.xml，并校验私钥派生出的公钥与Info.plist中SUPublicEDKey一致，确保更新链路端到端安全。

也就是说：只需手动迁移这一次，之后所有新版本都会经由 Sparkle 自动完成 App 替换，扩展随之更新，无需再走 Finder 手动拖拽流程。

小结

如果你在迁移过程中遇到问题，可以查阅仓库内对应语言版本的迁移指南（如 docs/zh_TW/guide/safari-migration.md），或前往项目的 GitHub Issues 反馈。

【免费下载链接】voyagerEnhancement suite for Gemini, AI Studio, Claude & ChatGPT — plus a prompt manager for any websites, DeepSeek Harness included. / 面向 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件；其中的提示词管理器可用于任意网站，如 DeepSeek Harness。项目地址: https://gitcode.com/gh_mirrors/ge/voyager