Voyager Safari 扩展迁移指南：从「Gemini Voyager」升级到「Voyager」的完整操作手册-平芜编程栈

AI 应用
前端

【免费下载链接】voyager

Enhancement 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

点击查看免费下载

本文基于 Voyager 项目的官方迁移文档（docs/ar/guide/safari-migration.md，英文版见 docs/en/guide/safari-migration.md），系统讲解自 v1.6.0 起 Safari 宿主应用更名后的一次性手动迁移流程，包括操作步骤、数据安全说明与常见误区，并辅以仓库源码佐证其底层实现原理。读完本文，你将掌握如何安全地完成旧版「Gemini Voyager.app」向新版「Voyager.app」的替换，并理解为什么该迁移只需要执行一次、之后即可回归自动更新。

背景：为什么需要一次手动迁移

从v1.6.0开始，Voyager 的 Safari 宿主应用由「Gemini Voyager」更名为「Voyager」。macOS 依据应用名称（.app文件名）来识别已安装的应用，因此如果直接安装新版本，新应用会与旧应用并存于同一台机器上，而 Safari 会同时看到两套扩展，进而可能出现：

扩展重复显示、功能入口混乱；
新旧两个扩展同时注入网页，行为互相干扰；
卸载时难以区分哪个应用对应哪个扩展。

所以官方将这次更名设计为一次性的手动替换：只需手动执行一次应用替换，之后所有更新都会重新回到自动更新通道，无需再手动操作。

值得说明的是，仓库源码中同样体现了这次改名的工程化处理。在宿主应用入口 Voyager/App/AppDelegate.swift 中定义了旧应用的固定路径常量：

/// The pre-rename host app. If it lingers in /Applications alongside the new /// "Voyager.app", both Safari extensions coexist and conflict. private let legacyAppPath = "/Applications/Gemini Voyager.app"

也就是说，旧应用会被精确识别为/Applications/Gemini Voyager.app，这正是本文迁移步骤中需要移除的目标对象。

你的数据是安全的：Bundle ID 未变

迁移最让人担心的是数据丢失。官方文档明确承诺：应用的 Bundle ID（包标识符）没有改变，因此以下数据全部得到保留：

你的文件夹结构（folders）；
提示词库 / 收藏库（prompt library）；
云同步数据（cloud sync）；
所有设置（settings）。

这一步只替换应用本身，完全不触碰数据文件。

从仓库配置可以得到佐证。在 Voyager/Voyager.xcodeproj/project.pbxproj 中，应用与扩展的PRODUCT_BUNDLE_IDENTIFIER均为：

com.yourCompany.Gemini-Voyager com.yourCompany.Gemini-Voyager.Extension

（发布构建中由正式签名替换为实际 Bundle ID。）改名前后该标识保持不变，这是 macOS 与 Safari 识别"同一个扩展"的关键——Safari 依据 Bundle ID 关联扩展与应用，只要它不变，已授权的扩展状态、存储数据与云同步凭据就能在应用替换后继续生效。

另外，Google Drive 数据目录也做了改名兼容处理。在 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" static func shouldRenameLegacyFolder( named name: String, canonicalNameAlreadyExists: Bool ) -> Bool { name == legacyName && !canonicalNameAlreadyExists } }

可以看到，旧的「Gemini Voyager Data」目录会被识别，并在新目录名尚不存在时自动迁移到「Voyager Data」。这进一步印证了改名只涉及应用外壳，底层数据标识与迁移路径都是完整设计好的。

迁移步骤（一次性手动操作）

按照官方文档，整个迁移只需四步，建议在下载并准备好新版 DMG 之后开始：

完全退出 Safari在 Safari 中按⌘Q彻底退出，而不是只关闭窗口。这一步很关键：如果 Safari 仍在运行，扩展与应用之间的关联可能还处于活动状态，干扰后续替换。
删除旧应用打开Finder → 应用程序，将旧的「Gemini Voyager.app」拖入废纸篓。
安装新应用打开你最新下载的 DMG 镜像，将「Voyager.app」拖入应用程序文件夹。
重新启用扩展重新打开 Safari →设置 → 扩展，启用「Voyager Extension」。

完成以上四步后，迁移即告完成。如果此前已经在 Safari 中启用过扩展，Bundle ID 不变意味着 Safari 会继续认可该扩展的身份。

两件千万不要做的事

官方文档特别强调了两个反向操作，务必避免：

不要同时保留两个应用。如果把旧的「Gemini Voyager.app」留在原地，两个扩展会在 Safari 中并存并冲突，产生与"未迁移"完全相同的问题。
不要在 Safari 的扩展面板中对旧扩展点击"卸载"（Uninstall）。该卸载动作指向的是旧应用，会绕开应用替换逻辑、使状态变得更加混乱。正确的做法只有一步：像上面第 2 步那样，把旧应用拖入废纸篓。

这一"警告"在源码中有对应的防护逻辑。宿主应用启动时（前台正常启动、而非后台静默唤起时）会检查旧应用是否仍存在，若存在则弹出一个本地提醒对话框（见 Voyager/App/AppDelegate.swift）：

private func promptLegacyAppRemovalIfNeeded() { guard !launchedForHandoff else { return } guard FileManager.default.fileExists(atPath: legacyAppPath) else { return } // 弹出警告：检测到旧应用仍位于应用程序文件夹 // 提供三个按钮："Move Old App to Trash" / "Migration Guide" / "Not Now" }

若用户选择Move Old App to Trash，应用会调用NSWorkspace.shared.recycle(_:)将旧应用直接移入废纸篓；若无法直接移入废纸篓，则在 Finder 中高亮选中该应用供用户手动处理（见 Voyager/App/AppDelegate.swift）。这意味着即使你忘记了手动删除旧应用，新版 Voyager 也会在你首次启动时主动提醒并协助完成清理。

迁移之后：更新自动恢复

完成这一次应用替换后，后续所有 Safari 版本更新都将通过应用内置的**自动更新器（Sparkle）**完成，不再需要任何手动替换操作。

Sparkle 的接入可以从源码与配置中确认：

Voyager/App/Info.plist 配置了自动更新相关的键值：
- SUAutomaticallyUpdate = true：自动下载并安装更新；
- SUEnableAutomaticChecks = true：启动自动检查更新；
- SUFeedURL：更新源指向发布版的appcast.xml；
- SUPublicEDKey：Sparkle 用于校验更新包签名的 EdDSA 公钥。
Voyager/App/AppDelegate.swift 中通过SPUStandardUpdaterController(startingUpdater: true, ...)初始化更新控制器，并在菜单中注入「Check for Updates…」入口（installCheckForUpdatesMenuItem）。
Voyager/Voyager.xcodeproj/project.pbxproj 将 Sparkle 作为远程 Swift 包依赖引入，锁定在 Voyager/Voyager.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved 中。

同时，应用自带的诊断功能（见 Voyager/App/NativeDiagnosticsService.swift）会报告更新的当前状态：自动检查是否开启、最近一次检查时间等，便于在迁移后确认更新通道已恢复正常。

常见疑问

Q1：迁移会影响云同步吗？不会。云同步（Google Drive / iCloud）的数据标识与存储位置不依赖应用名。Google Drive 侧的旧目录「Gemini Voyager Data」会被自动识别并迁移到新目录名（见上文VoyagerGoogleDriveFolderIdentity逻辑）；iCloud / CloudKit 侧则通过固定的容器标识与 Bundle ID 关联，替换应用后同步状态保持不变。

Q2：如果我已经误点了旧扩展的"卸载"怎么办？旧扩展的卸载状态会随旧应用的删除而自然失效。请完成上述标准四步（退出 Safari → 删除旧应用 → 安装新应用 → 重新启用「Voyager Extension」），并在设置中重新开启扩展即可。

Q3：新版 Voyager 为什么不自动帮我替换旧应用？macOS 不允许应用在运行时自行删除另一个正在运行的.app，因此官方选择用"启动时检测 + 提醒 + 一键移入废纸篓"的方式引导用户完成替换，既符合系统安全模型，也避免误删数据。

结语

从「Gemini Voyager」到「Voyager」的更名迁移虽然需要一次手动操作，但整个过程在官方设计上做到了"数据零风险、步骤四步内、一次之后永不再手动"。结合源码可见，新版应用不仅主动检测旧应用残留并辅助清理，Google Drive 与 iCloud 的数据迁移也都有完整兼容逻辑。相关中文说明还可参考仓库根目录的 docs/guide/safari-migration.md 与其他语言版本（docs/en/guide/safari-migration.md 等）。