故障排查

针对你最可能遇到的问题的实用修复。

认证失败

如果一个命令返回认证错误，请确认 CLI 正在解析哪个身份（如果有的话）：

suya auth whoami     # calls the API and prints the resolved identity
suya auth status     # local auth status, no server call

对于 agent 和 CI，请确保 SUBAYA_API_KEY 在运行 suya 的 shell 中已导出：

echo "${SUBAYA_API_KEY:?SUBAYA_API_KEY is not set}"

记住凭据优先级：--token 标志胜出，然后是 SUBAYA_API_KEY，再然后是本地存储的 OAuth 令牌。 如果你很久以前登录过，一次全新的 suya auth login 会重新建立本地令牌。参见 认证与 API 密钥。

命令命中了错误的主机

每个命令默认都与 https://subaya-dev.com 通信。如果请求正在失败或落在意料之外的地方，请检查 你没有传入一个无意的 --host：

suya auth whoami --host https://subaya-dev.com

只在你打算面向非默认 API 端点时才覆盖 --host。

suya sim run 找不到测试平台

--tb 路径是在 --source 树内解释的，而非相对于你 shell 的工作目录。如果运行报告测试平台 缺失，请验证该路径在你上传的源代码目录内能够解析：

suya sim run --source . --tb tb/top_tb.sv --top top --tool ryusim

需要检查两件事：

• --tb 路径在 --source 目录下存在。
• --source 树为 4 MB 或更小——在提交前修剪构建产物和大型二进制文件。

完整的仿真界面请参见 CLI: sim。

suya repo connect / repo create 失败

两个 repo 命令都需要通过 --installation 提供 GitHub App 安装 id：

suya repo connect --installation <id> --owner <o> --repo <r>
suya repo create  --installation <id> --name <n>

如果你还没有安装 id，请先安装 GitHub App——参见 连接 GitHub 仓库。用以下命令确认当前的连接状态：

suya repo status

过期的 CLI

如果某个命令或标志缺失，或行为与这些文档不符，你的 CLI 可能已过期。检查并升级：

suya version            # show version metadata
suya update --check     # report whether a newer release exists
suya update             # upgrade to the latest release

仍然卡住？

• 用 -v/--verbose 重新运行以获取额外诊断，或用 --json 获取机器可读的输出。
• 在 状态 页面检查服务健康。
• 在 CLI 参考 中浏览完整的命令界面。