常见问题排查
定位连接失败、服务缺失、开发会话冲突和打包错误。
核对日期：2026 年 9 月 11 日
本页目录
终端找不到 trove#
在 Trove 开发页面安装或检查命令行工具，打开新终端，确认当前选择的可执行文件：
command -v trove
trove --version
trove curio --help
Shell 命令可能指向应用包内部。重新构建另一个本地二进制，不会更新该应用包。先确认注册目标，再判断 CLI 与 Host 是否同一构建。若另一个 Host 可执行文件占用了数据目录，正常退出那个 Host，再使用目标构建重试。
Host Bridge 不可用#
bridge.host_unavailable 表示页面没有 Host 注入的桥接。通过 trove curio dev 或 Trove 中已安装的 Curio 打开页面。普通浏览器只渲染 UI，不提供原生 API；浏览器测试请显式创建 Mock 客户端。
bridge.reloaded、bridge.disconnected 表示客户端连接已结束。取消过时的 UI 工作，并建立新的页面或客户端连接。对已显式 disconnect 的客户端再次调用 ready，不能恢复它。
开发无法启动#
trove curio check --json
trove --verbose curio dev
| 现象 | 检查与恢复 |
|---|---|
| 初始化拒绝目录 | init 要求新目录，空目录也不例外；更换路径或按已有项目指南接入 |
| 缺少依赖 | 使用工程选择的包管理器安装，保留 SDK vendor 包 |
| UI 服务等待超时 | 对齐 Manifest URL 和实际端口；动态端口必须读取 TROVE_DEV_PORT |
| 地址被占用 | 停止遗留 UI 进程或换端口；已有服务用 --no-start-ui --ui-url ... 连接 |
| Curio ID 已运行 | 结束该 Curio 的旧开发会话，独立工程使用不同 ID |
| Host 可执行文件冲突 | 检查 CLI 注册和运行中的 Host，不同可执行文件不能静默接管数据目录 |
不要通过删除用户数据规避开发冲突。Ctrl-C 只停止当前 CLI 会话，不会退出所有 Host 会话。
请求与服务错误#
| Code | 含义与下一步 |
|---|---|
request.invalid_params | 检查 Contract 中的参数名、类型和必需字段 |
request.invalid_options | 检查 timeoutMs 为有限数字且在 SDK 范围内 |
request.timeout | 查看提供方日志和耗时，只有可安全重复的操作才重试 |
request.cancelled | 请求已取消，结束 UI 加载状态，不展示成功结果 |
service.not_found | 查询已注册服务，安装或启动目标提供方 |
service.method_not_found | 通过 describe 检查方法是否缺失或仍在规划中 |
service.version_mismatch | 对齐声明的兼容范围与已安装服务版本 |
service.contract_violation | 对照 JSON Contract 检查参数、结果与事件 |
provider.disconnected | Backend 连接结束，检查进程输出与生命周期 |
self.unavailable | 缺少操作所需的 Curio 或 Backend 上下文 |
host.storage.value_too_large / host.storage.quota_exceeded | 大型数据改用文件，或减少存储内容 |
保留 TroveError 的 code、message 和可用的 traceId。retryable 为 true 不代表自动重试。实现功能前查看 Host 能力状态，避免调用规划接口。
开发正常，安装后失败#
对齐 ui.entry 与构建输出，将依赖资源放入 package.files。使用相对资源路径，检查动态 import，在开发服务停止时测试安装版。生产 Manifest 不保留 development.ui.url。
Backend 入口必须是目标平台的真实可执行文件，检查权限、架构和运行依赖。pack --dry-run 不能证明尚未构建的产物有效，应实际执行 pack 并确认成功。
下载返回登录页时，让 Release 附件可以匿名访问。Git 认证只覆盖软件源索引与仓库，不会转发到 HTTP 包下载。
准备有用的复现信息#
记录 Host/CLI 版本、macOS 版本与架构、Curio ID/版本、失败命令、预期与实际行为。复制调试控制台的相关筛选输出，附上能复现的最小 Manifest 或请求，去除密钥和个人数据。
在新的开发会话中重试最小失败步骤。测试与调试解释日志限制，以及 Mock、原生接入与安装包验证的区别。