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 中通过测试保证只有存在唯一、无歧义的旧名称目录时才执行自动迁移如果新名称目录已存在则不会覆盖。可见更名迁移是整套设计的一部分用户的文件夹、提示词库、云同步与设置均被完整保留。迁移步骤四步完成官方文档给出的操作流程非常简洁共四步完全退出 Safari在 Safari 中按下⌘Q真正退出而不是只关闭窗口。这一步很关键因为 Safari 在运行期间会锁定正在使用的扩展不彻底退出会导致后续替换不干净。删除旧 App打开「访达 → 应用程序」Finder → Applications把旧的「Gemini Voyager.app」拖入废纸篓。安装新 App打开新下载的 DMG把其中的「Voyager.app」拖进「应用程序」文件夹。重新启用扩展重新打开 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 手动拖拽流程。小结维度说明触发原因v1.6.0 起宿主 App 由「Gemini Voyager」更名为「Voyager」macOS 按名称识别导致新旧并存数据影响Bundle ID 未变文件夹、灵感库、云同步、设置全部保留操作次数仅需手动执行一次核心动作完全退出 Safari → 删除旧 App → 安装新 App → 重新启用扩展禁忌不要保留两个 App不要在 Safari 扩展面板点「卸载」后续更新Sparkle 自动更新接管无需再手动替换如果你在迁移过程中遇到问题可以查阅仓库内对应语言版本的迁移指南如 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考