故障排查
常见的安装、认证、计费、打包与更新问题的解决方法。
按领域分组的"症状 → 可能原因 → 解决"。每条都链接回拥有该子系统的指南。拿不准时，
打开日志页面（或用 pnpm dev 开启开发者工具）
——大多数失败都会记录清晰的原因。
| 症状 | 可能原因 | 解决 |
|---|
postinstall 在原生依赖上失败 | Node/工具链不匹配 | 使用 Node `^20.19 |
| pnpm 版本不对 | packageManager 锁定未生效 | 启用 corepack 或安装 pnpm 11.1.3。参见安装。 |
| 端口被占用 | 残留的 pnpm dev | 停掉另一个进程；scripts/dev.mjs 掌管开发端口。 |
| 空白窗口 / 渲染进程崩溃 | 挂载前的渲染进程异常 | 运行 pnpm dev 并打开开发者工具；查看控制台与日志页面。ErrorBoundary 应显示带主题的兜底界面。 |
| 症状 | 可能原因 | 解决 |
|---|
启动时出现 SupabaseConfigErrorScreen | 认证已开但 Supabase 环境变量缺失/无效 | 设置 VITE_SUPABASE_URL + VITE_SUPABASE_PUBLISHABLE_KEY，或设置 VITE_AUTH_ENABLED=false。参见认证。 |
| 邮箱确认/重置从不跳回应用 | 深链 scheme 未注册，或重定向 URL 未在 Supabase 中加入白名单 | 确认 soar-electron:// 处理程序已注册，并在 Supabase → Auth → URL Configuration 下添加重定向 URL。参见深度链接。 |
深链在打包版可用但 dev 下不行 | 开发模式的协议注册因平台而异且不稳定 | 用 pnpm build:unpack 构建验证。参见深度链接。 |
| 登录无法跨重启保留 | safeStorage 加密不可用（如无 Linux 钥匙串） | 确保有可用的操作系统钥匙串；会记录一个 SecureStorageError（ENCRYPTION_UNAVAILABLE）。参见设置存储。 |
| 症状 | 可能原因 | 解决 |
|---|
| 没有账单 UI / 功能始终锁定 | 账单标志关闭 | 设置 VITE_BILLING_ENABLED=true。参见账单。 |
| 结账能打开但什么都没解锁 | 产品 ID 未设置，或 webhook 从未写入行 | 设置 VITE_CREEM_PRODUCT_*；确认 subscriptions 行出现。参见Creem 配置。 |
| 授权始终不更新 | 读取本地购买状态而非 Supabase | 授权只从 subscriptions 表读取（RLS 仅 SELECT）。参见账单。 |
| Webhook 签名校验失败 | CREEM_WEBHOOK_SECRET 不对 | 重新设置该 Edge 密钥；它只作为 Supabase 密钥存在，绝不放在应用 .env 中。参见Creem 配置。 |
| 症状 | 可能原因 | 解决 |
|---|
| Windows 上通知静默 | AUMID 未设置，或以未打包方式运行 | 模板在启动时设置 APP_USER_MODEL_ID；Windows 通知在已安装构建上最可靠。确认 settings.notifications 已开。参见通知与快捷键。 |
| 某个快捷键无反应 | 加速键冲突，或非 global 作用域 | 检查关于重复加速键的启动警告；只有 global 作用域的快捷键才系统级注册，而默认不附带任何此类快捷键。参见通知与快捷键。 |
| 窗口在屏幕外打开 | 保存的边界已失效 | 存储会自动把无效边界重新居中；必要时删除 userData 中的 window-state.json。参见窗口、菜单与托盘。 |
| 外部链接在应用内打开或被拦 | 不是 https:/mailto: | openExternal 只允许这些 scheme。参见窗口、菜单与托盘。 |
| 症状 | 可能原因 | 解决 |
|---|
| 更新检查报 feed 404 | UPDATE_SERVER_URL 错误，或未上传 latest*.yml | 核对更新源 URL，并确认元数据 + 安装包 + blockmap 都已托管。参见自动更新。 |
| macOS 无法应用更新 | 构建未签名 + 未公证 | Gatekeeper 拒绝未签名的替换；请签名并公证。参见打包。 |
dev 下没有更新 | 未打包时更新器是空操作 | 用打包构建测试更新。参见自动更新。 |
| 完全没有更新 UI | VITE_AUTO_UPDATE_ENABLED=false，或 autoUpdate 设置关闭 | 启用该标志，并在设置 → 更新中打开自动更新。 |
| 症状 | 可能原因 | 解决 |
|---|
| 应用图标错误或缺失 | 编辑了源 SVG 但未重新生成位图 | 重跑 docs/APP_ICONS.md 的步骤。参见打包。 |
| 公证失败或被跳过 | APPLE_* 环境变量未设置 | 无凭据时钩子空操作（未签名构建）；设置 APPLE_ID/APPLE_APP_SPECIFIC_PASSWORD/APPLE_TEAM_ID。参见打包。 |
snap 目标失败 | 在非 Linux 上构建 Linux 目标 | 在 Linux（或 CI）上构建 Linux 产物；把目标列表裁剪到你实际发布的那些。 |
| Windows SmartScreen 告警 | 安装包未签名 | 提供 CSC_LINK/CSC_KEY_PASSWORD；EV 证书可立即消除信誉问题。 |
| 症状 | 可能原因 | 解决 |
|---|
渲染出像 nav.home 这样的原始键 | 翻译键缺失 | 把该键同时加入 app/locales/en/*.json 与 app/locales/zh/*.json。参见国际化。 |
