> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/troubleshooting.md).

# 身份验证故障排查

根据准确的控制台消息、错误代码和原因，排查并修复 Convai Unity SDK 在 API Key 和 Auth Token 模式下的身份验证失败问题。

使用准确的控制台消息或 `SessionErrorCodes` 值，诊断任一身份验证模式下的连接失败。连接尝试失败后，或配置的令牌端点无法正常访问时，请使用此页面。

### 症状对照表

| 症状                                                                                                 | 可能原因                                                                            | 解决方法                                                                                 | 验证                          |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------- |
| `Auth token endpoint must use HTTPS, except for HTTP loopback URLs used during local development.` | 配置的 **令牌端点 URL** 使用的是普通 HTTP，且不是回环地址。                                           | 将端点改为 HTTPS，或仅在本地开发时使用 `http://127.0.0.1` / `http://localhost` 地址。                   | 重新连接；现在端点请求会成功，不再因验证失败。     |
| `Auth token endpoint returned no response.` / `...transport failed.`                               | 无法访问端点——主机错误、网络故障，或服务器已宕机。                                                      | 确认端点 URL 正确，并且服务器正在运行，且可从构建目标所在的网络访问。                                                | 重新连接，并确认请求已出现在服务器的访问日志中。    |
| `Auth token endpoint returned HTTP {code}.`                                                        | 端点返回了非 2xx 状态码。                                                                 | 检查服务器日志中的返回状态码，并修复根本原因（身份验证、速率限制或服务器错误）。                                             | 待服务器返回 `200`.               |
| `Auth token endpoint returned malformed JSON.`                                                     | 端点响应正文不是有效的 JSON。                                                               | 返回包含令牌字段的 JSON 对象，例如 `{"apiAuthToken": "..."}`.                                      | 重新连接；SDK 能够无错误地解析响应。        |
| `Auth token response field '{field}' was not found.`                                               | 响应 JSON 中没有在 **令牌响应字段** 中配置的字段（默认值为 `apiAuthToken`).                            | ） **令牌响应字段** 应与端点实际返回的 JSON 键一致；如果字段嵌套，还需包含点分隔路径，例如 `data.token`.                    | 重新连接；SDK 会从修正后的字段中读取令牌。     |
| `...was empty.` （已找到响应字段，但字段值为空）                                                                   | 响应字段存在，但其值为空字符串。                                                                | 修复生成令牌的服务器逻辑——请求虽然成功返回，但没有令牌值。                                                       | 重新连接并确认该字段已填充。              |
| `...contained an invalid expirationTime.`                                                          | 可选的 `expirationTime` 字段不是可解析的时间戳。                                               | 请将 `expirationTime` 设为 ISO-8601 格式的字符串；如果不使用此字段，则完全省略。                               | 重新连接；SDK 会接受该响应。            |
| `身份验证令牌委托未返回任务。` / `……返回了空令牌。`                                                                     | 一个 `DelegateAuthTokenProvider` lambda 表达式返回了 `null` 或空字符串，而不是令牌。                | 请修复该委托，使其始终返回非空令牌字符串，或抛出异常/等待正确的失败结果。                                                | 重新连接；该委托会返回有效令牌。            |
| `身份验证令牌委托失败（{ExceptionType}）。`                                                                     | 该 `DelegateAuthTokenProvider` lambda 表达式抛出了异常。                                  | 请检查消息中的异常类型，并修复委托中的根本故障。                                                             | 待委托不再抛出异常后重新连接。             |
| `Auth Token 模式要求注册 IConvaiAuthTokenProvider 或配置端点 URL。` (`ConfigAuthTokenProviderMissing`)         | **身份验证模式** 为 **身份验证令牌**，但未注册提供程序，也未配置 **令牌端点 URL** 。                            | 请在首次连接前注册 `IConvaiAuthTokenProvider` ，或在 **令牌端点 URL** 中 **Convai > 设置 > 凭据**.        | 重新连接；错误不再出现。                |
| `身份验证令牌提供程序失败（{ExceptionType}）。` / `……无法解析令牌。` / `……返回了空令牌。`                                       | 已注册的 `IConvaiAuthTokenProvider` 实现抛出了异常、执行失败或返回了空令牌。                            | 请检查异常类型或失败原因，并修复提供程序中的 `GetTokenAsync` 方法。                                           | 待提供程序返回有效的非空令牌后重新连接。        |
| `使用显式身份验证令牌进行连接，要求在 Convai 项目设置中启用身份验证令牌模式。` (`ConfigAuthTokenModeRequired`)                       | `ConnectWithAuthTokenAsync` 被调用时， **身份验证模式** 仍为 **API 密钥**.                     | 将 **身份验证模式** 设为 **身份验证令牌** 位于 **Convai > 设置 > 凭据** 之前调用 `ConnectWithAuthTokenAsync`. | 重新连接；显式令牌已被接受。              |
| `A non-empty Convai auth token is required.`                                                       | `ConnectWithAuthTokenAsync` 调用时传入了空或仅包含空白字符的 `authToken` 参数。                    | 请确认登录流程已获取令牌，然后再调用 `ConnectWithAuthTokenAsync`；不要传入占位值。                              | 使用真实令牌重新连接。                 |
| `A non-empty end-user ID is required.` / `A non-empty end-user name is required.`                  | `ConnectWithAuthTokenAsync` 调用时传入了空的 `endUserId` 或 `endUserName` 参数。            | 每次调用都传入非空且稳定的账户 ID 和显示名称。                                                            | 填好这两个参数后重新连接。               |
| 连接失败，错误为 `Connection token is invalid` (`ConnectionInvalidToken`)                                  | Convai 拒绝了该令牌——令牌已过期、格式错误，或不是你的端点最近签发的令牌。                                       | 请确认端点每次请求都会返回新签发的令牌，并且没有缓存层提供过期令牌。                                                   | 重新连接；新令牌已被接受。               |
| 连接失败，HTTP 状态为 `401`                                                                                | 房间连接请求在传输层被拒绝，SDK 会将此情况映射为 `ConnectionInvalidToken`.                            | 请确认端点或提供方返回的是 `apiAuthToken` ，而不是游戏登录令牌、刷新令牌或 Convai 账户 API 密钥；同时确认令牌尚未过期。           | 重新连接；连接成功。                  |
| `An API key must be saved in Convai Project Settings before the Editor can mint an auth token.`    | 仅限编辑器使用的回退提供方尝试运行，但尚未保存 API 密钥。                                                 | 在 **Convai > 设置 > 凭据**中保存 API 密钥，即使处于身份验证令牌模式也不例外，这样编辑器回退机制才能在本地签发令牌。                | 再次进入播放模式；回退提供方运行成功。         |
| 身份验证令牌模式在编辑器中可用，但在玩家构建中立即失败                                                                        | 仅限编辑器使用的回退提供方（`ConvaiEditorApiKeyAuthTokenProvider`）暗中弥补了缺失的提供方或端点。它不会编译进玩家构建中。 | 注册一个运行时 `IConvaiAuthTokenProvider`，或配置一个 **令牌端点 URL**，这样播放器构建版本就有了实际的凭据来源。           | 运行构建版本；连接应能成功，且无需使用编辑器回退方案。 |
| 在 Play 模式下更改端点配置不会影响当前会话                                                                           | 每次尝试连接时都会解析一次凭据，而非持续解析。                                                         | 更改端点、标头或提供程序后，请结束会话并重新连接。                                                            | 下一次连接尝试将使用更新后的配置。           |

### 端点不是 HTTPS

**症状：** 控制台记录了 `Auth token endpoint must use HTTPS, except for HTTP loopback URLs used during local development.`

**原因：** `EndpointAuthTokenProvider` 会在每次请求前验证 **令牌端点 URL** ，并拒绝使用除 `https://`以外的协议，除非主机是环回地址（`127.0.0.1` 或 `localhost`），供本地开发使用。

**解决方法：** 将端点更改为 `https://`。如果要对接本地服务器进行测试，请使用环回地址，而不是局域网 IP 或公共 HTTP 隧道。

**验证：** 重新连接。请求会发送到服务器，而不会在发送前因验证失败而终止。

### 端点响应中缺少令牌字段

**症状：** 控制台记录了 `Auth token response field 'apiAuthToken' was not found.` （或配置的其他字段名）。

**原因：** `EndpointAuthTokenProvider` 会解析 JSON 响应并查找 **令牌响应字段**，其默认值为 `apiAuthToken` ，并支持诸如 `data.token`这样的点分路径。如果服务器响应使用了不同的键，或者令牌嵌套在所配置字段无法匹配的路径下，解析就会失败。

**解决方法：** 可以让服务器在顶层的 `apiAuthToken` 字段中返回令牌，或者更新 **令牌响应字段** ，在 **Convai > Settings > Credentials** 中将其设置为与服务器的实际响应结构相匹配。

**验证：** 重新连接。SDK 会从响应中读取令牌，而不是报告缺少字段。

### 提供程序注册过晚

**症状：** 进入播放模式或开始构建后，首次连接尝试会失败，并显示 `Auth Token mode requires a registered IConvaiAuthTokenProvider or a configured endpoint URL.`，即使代码已注册提供程序也是如此。

**原因：** `ConvaiAuthTokenProviderRegistry` 是一个进程内静态注册表，会在 `RuntimeInitializeLoadType.SubsystemRegistration` 时自动重置——每次域重载和每次进入播放模式都会清空该注册表。如果在 SDK 首次尝试连接之后才由组件注册提供程序，或者重载后没有重新注册提供程序，那么 SDK 需要使用它时，注册表便为空。

**修复方法：** 尽早注册提供程序，例如在场景引导组件的 `Awake` 方法中注册；并在任何可能清空注册表的域重载或场景重载后重新注册。如果登录 SDK 是异步初始化的，请立即注册提供程序，并让提供程序自身的令牌获取逻辑在内部等待登录初始化完成——不要延迟注册。

**验证：** 修复后重新连接。 `IsRegistered` 会在注册后立即反映提供程序的状态，且连接会成功解析令牌，而不是报告缺少提供程序。

### 显式令牌连接未选择 Auth Token 模式

**症状：** `ConnectWithAuthTokenAsync` 立即失败，并显示 `Explicit auth-token connections require Auth Token mode in Convai Project Settings.`

**原因：** `RoomConnectionRuntimeAdapter` 会检查当前凭据提供程序是否实现了显式令牌契约。只有在 **Auth Mode** 为 **Auth Token**时才会如此。若项目仍处于 `ConnectWithAuthTokenAsync` 模式下调用 **API Key** ，则会在发出任何网络请求之前因未通过此检查而失败。

**修复方法：** 在 **Convai > Settings > Credentials** 中将 **Auth Mode** 设置为 **Auth Token**。此路径无需配置 **Token Endpoint URL** 或注册提供程序——调用方会直接提供令牌。

**验证：** 使用 `ConnectWithAuthTokenAsync`重新连接。该调用会通过凭据验证，不再立即失败。

### 连接时 HTTP 401

**症状：** 房间连接请求返回 HTTP `401`，SDK 将其报告为 `Connection token is invalid` (`ConnectionInvalidToken`).

**原因：** Convai 拒绝了通过 `API-AUTH-TOKEN` 标头发送的令牌。令牌过期、已被使用，或实际上不是 Convai 的 `apiAuthToken` 时会发生这种情况。例如，端点或提供程序可能意外返回了游戏登录令牌或 Convai 账户 API 密钥。

**修复方法：** 确认端点或提供程序返回的是 Convai 自己的令牌签发响应中的 `apiAuthToken` 字段值，而不是其他凭据；并确认每次连接都会重新签发令牌，而不是从可能过期的缓存中提供令牌。

**验证：** 重新连接。使用新签发且来源正确的令牌即可成功连接。

### 仅编辑器中可用的备用提供程序未生效

**症状：** 在 Unity 编辑器中，Auth Token 模式仍然报错： `Auth Token mode requires a registered IConvaiAuthTokenProvider or a configured endpoint URL.`，即使已保存 API 密钥也是如此。

**原因：** `ConvaiEditorApiKeyAuthTokenProvider` 仅在以下三个条件全部满足时才会自动注册： **Auth Mode** 为 **Auth Token**、已保存 API 密钥，且未配置 **Token Endpoint URL** 。如果设置了 **Token Endpoint URL** （即使 URL 无效），备用提供程序也不会启用，因为显式指定的端点优先。

**修复方法：** 若要在没有真实后端的情况下进行本地编辑器测试，请清空 **Token Endpoint URL** ，并确认已在 **Convai > Settings > Credentials**中保存 API 密钥。除编辑器测试外，不要依赖此备用提供程序——它在构建玩家时会被完全排除，因此除非配置了运行时提供程序或端点，否则构建版本也会出现同样的问题。请参阅 [发布安全构建](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/ship-a-secure-build.md).

**验证：** 进入 Play 模式。编辑器会使用已保存的 API 密钥签发令牌，并成功建立连接。

### 后续步骤

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>配置 Auth Token 模式</strong><br>切换到 Auth Token 模式，并在 Project Settings 中配置令牌端点。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/configure-auth-token-mode.md">配置 Auth Token 模式</a></td></tr><tr><td><strong>编写自定义令牌提供程序</strong><br>实现 IConvaiAuthTokenProvider，从你自己的登录流程中获取令牌。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/custom-token-provider.md">编写自定义令牌提供程序</a></td></tr><tr><td><strong>发布安全构建</strong><br>了解构建处理器会移除哪些内容，以及令牌端点的 WebGL CORS 要求。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/ship-a-secure-build.md">发布安全构建</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
