深度链接

本模板注册了一个自定义 URL scheme，使操作系统能把 soar-electron:// 链接交给应用。传入的 URL 会被解析为类型化的 app intent，对照路由白名单校验，再作为经校验的 Conveyor 事件送达渲染进程。有两个真实的消费方依赖这条路径：Supabase 认证重定向与账单成功跳回。

当前 scheme 为 soar-electron（shared/constants.ts 中的 PROTOCOL_SCHEME）。pnpm rebrand --scheme <name> 会在所有位置改写它——参见品牌定制。下文每个示例都使用 soar-electron://。

注册

scheme 在两个必须一致的位置注册：

位置	作用
`lib/main/main.ts`	启动时 `app.setAsDefaultProtocolClient(PROTOCOL_SCHEME)` 将应用注册为操作系统的处理程序。
`electron-builder.yml`	`protocols` 块把 scheme 烘焙进安装包，使打包构建在安装后拥有它。

在开发模式下注册有特殊处理。由于正在运行的二进制是 Electron 本身，main.ts 会传入 Electron 可执行文件外加项目路径，让操作系统能正确地重新启动应用：

// lib/main/main.ts
if (process.defaultApp) {
  if (process.argv.length >= 2) {
    app.setAsDefaultProtocolClient(PROTOCOL_SCHEME, process.execPath, [resolve(process.argv[1])])
  }
} else {
  app.setAsDefaultProtocolClient(PROTOCOL_SCHEME)
}

一个 URL 如何变成一次导航

每个平台最终都汇入同一个解析器 parseArgvForIntents （lib/main/argv-intents.ts），它把 soar-electron://<route> 字符串（或 --route=<route> 标志）转成类型化的 intent，并丢弃任何校验不通过的内容。

操作系统送来 URL

macOS 触发 app.on('open-url')。冷启动时这可能在应用就绪之前到达，因此 main.ts 会把 URL 缓冲在 pendingProtocolUrls 中，初始化后再排空。
Windows / Linux 把 URL 作为 argv 项交给第二个进程启动。单实例锁（app.requestSingleInstanceLock()）将其路由到 app.on('second-instance')，后者聚焦已有窗口并解析 argv。

解析为类型化 intent

parseArgvForIntents 提取路由并用 appIntentSchema 校验。路由必须是 navigationRouteSchema（白名单）的成员，否则该 intent 被丢弃：

// lib/conveyor/schemas/event-schema.ts
export const navigationRouteSchema = z.enum([
  '/home',
  '/showcase', '/showcase/components', '/showcase/file', '/showcase/todos', // [template-demo]
  '/account', '/settings', '/about', '/logs', '/update', '/billing',
])

派发到渲染进程

AppIntentService.dispatch()（lib/main/app-intents.ts）会再次校验该 intent，并作为 app-intent Conveyor 事件发送给渲染进程。如果渲染进程尚未就绪，intent 会排队，等它发出就绪信号（app-intents-ready）后再一并冲刷——因此一个冷启动应用的链接仍会落在正确的路由上。

渲染进程导航

app/app.tsx 订阅 app-intent 事件并调用路由器。由于该路由早已对照白名单校验过，渲染进程可以信任它。

托盘与菜单导航复用完全相同的 dispatch 路径——当它们抵达渲染进程时，一次托盘 "设置"点击与一个 soar-electron://settings URL 已无从区分。

两个真实的消费方

深度链接并不只服务于演示——认证与账单流程都依赖它们：

Supabase 认证重定向。 邮箱确认与密码重置通过该 scheme 跳回桌面应用。请把重定向 URL 加入你的 Supabase 项目，使跳转能回到应用内——参见 Supabase 配置与认证。
账单成功跳回。 在浏览器完成 Creem 结账后，流程会跳回 soar-electron://billing?status=success&orderId=…（可选地经由托管的 BILLING_SUCCESS_URL 页面）。/billing 路由随后从 Supabase 刷新授权——参见账单。

随附的 supabase/pay-success.sample.html 目前仍构造一个 soar://billing 链接。请以 soar-electron:// 为准，并在托管该样例时修正它。

测试深度链接

在应用运行时，从终端触发该 scheme：

open 'soar-electron://settings'

start soar-electron://settings

xdg-open 'soar-electron://settings'

窗口应聚焦并导航到设置。也可以试试 soar-electron://about 或 soar-electron://billing。一个未知路由（例如 soar-electron://nope）会被解析、未通过白名单校验，并被静默忽略——这正是预期行为。

在 dev 下，操作系统的协议注册依赖上文特殊处理的 setAsDefaultProtocolClient 调用，相比打包安装可能不太稳定（在 Linux 桌面环境下尤甚）。若某个链接在 dev 下不触发，请先在 pnpm build:unpack 构建上验证，再判断是否为缺陷——参见疑难排查。

注册