> 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).

# 身份验证故障排查

根据准确的控制台消息、错误代码，以及 API Key 和 Auth Token 模式的成因，修复 Convai Unity SDK 身份验证失败。

使用确切的控制台消息或 `SessionErrorCodes` 使用 SDK 返回的值。连接尝试失败后，或您配置的令牌端点未被正确访问时，请使用此页面。

### 症状表

| 症状                                                                                             | 可能原因                                                                               | 修复方法                                                                                          | 验证                        |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------- |
| `身份验证令牌端点必须使用 HTTPS，但本地开发期间使用的 HTTP 回环 URL 除外。`                                                | 已配置的 **令牌端点 URL** 是普通 HTTP，且不是回环地址。                                                | 将端点改为 HTTPS，或使用 `http://127.0.0.1` / `http://localhost` 地址，仅用于本地开发。                           | 重新连接；现在端点请求会成功，而不是在校验时失败。 |
| `身份验证令牌端点未返回任何响应。` / `...传输失败。`                                                                | 端点无法访问——主机错误、网络故障，或服务器已关闭。                                                         | 确认端点 URL 正确，并且服务器正在运行，且可从构建目标的网络访问。                                                           | 重新连接，并确认请求已到达您服务器的访问日志。   |
| `身份验证令牌端点返回了 HTTP {code}。`                                                                     | 端点返回了非 2xx 状态。                                                                     | 在服务器日志中查看返回的状态码，并修复根本故障（认证、速率限制、服务器错误）。                                                       | 在服务器返回后重新连接 `200`.        |
| `身份验证令牌端点返回了格式错误的 JSON。`                                                                       | 端点的响应体不是有效的 JSON。                                                                  | 返回一个包含 token 字段的 JSON 对象，例如 `{"apiAuthToken": "..."}`.                                        | 重新连接；SDK 解析响应时不会出错。       |
| `未找到身份验证令牌响应字段“{field}”。`                                                                      | 响应 JSON 不包含在以下位置配置的字段 **令牌响应字段** (默认 `apiAuthToken`).                              | 匹配 **令牌响应字段** 到您的端点返回的实际 JSON 键名，包括嵌套字段的点路径，例如 `data.token`.                                  | 重新连接；SDK 将从更正后的字段读取令牌。    |
| `...为空。` (已找到响应字段，但为空)                                                                         | 响应字段存在，但其值为空字符串。                                                                   | 修复生成令牌的服务器逻辑——它虽然成功返回，但没有令牌值。                                                                 | 重新连接并确认该字段已有内容。           |
| `...包含无效的 expirationTime。`                                                                     | 可选的 `expirationTime` 字段不是可解析的时间戳。                                                  | 返回 `expirationTime` 请将其作为 ISO-8601 字符串返回；如果不使用该字段，则完全省略它。                                     | 重新连接；SDK 接受该响应。           |
| `身份验证令牌委托未返回任务。` / `...返回了空令牌。`                                                                | 某个 `DelegateAuthTokenProvider` lambda 返回了 `null` 而不是令牌，而是空字符串。                     | 修复委托，使其始终返回非空的令牌字符串，或抛出/等待适当的失败。                                                              | 重新连接；委托返回有效令牌。            |
| `身份验证令牌委托失败（{ExceptionType}）。`                                                                 | 该 `DelegateAuthTokenProvider` lambda 抛出了异常。                                        | 检查消息中的异常类型，并修复委托中的根本故障。                                                                       | 在委托停止抛出异常后重新连接。           |
| `Auth Token 模式需要已注册的 IConvaiAuthTokenProvider 或已配置的端点 URL。` (`ConfigAuthTokenProviderMissing`) | **认证模式** 为 **Auth Token**，但未注册提供程序，且未 **令牌端点 URL** 配置。                             | 注册一个 `IConvaiAuthTokenProvider` ，然后再进行首次连接；或者配置一个 **令牌端点 URL** 中的 **Convai > Settings > 凭据**. | 重新连接；错误不再出现。              |
| `身份验证令牌提供程序失败（{ExceptionType}）。` / `...未能解析令牌。` / `...返回了空令牌。`                                 | 您注册的 `IConvaiAuthTokenProvider` 实现抛出异常、失败，或返回了空令牌。                                 | 检查异常类型或失败原因，并修复 `GetTokenAsync` 您提供程序中的问题。                                                    | 在提供程序返回有效且非空的令牌后重新连接。     |
| `显式的身份验证令牌连接需要在 Convai 项目设置中启用 Auth Token 模式。` (`ConfigAuthTokenModeRequired`)                 | `ConnectWithAuthTokenAsync` 在以下情况下被调用 **认证模式** 仍然是 **API 密钥**.                     | 将 **认证模式** 到 **Auth Token** 中的 **Convai > Settings > 凭据** 在调用 `ConnectWithAuthTokenAsync`.    | 重新连接；显式令牌会被接受。            |
| `需要非空的 Convai 身份验证令牌。`                                                                         | `ConnectWithAuthTokenAsync` 在传入空值或仅包含空白字符的 `authToken` 参数时被调用。                     | 请确认您的登录流程在调用前已获取令牌 `ConnectWithAuthTokenAsync`；不要使用占位符值调用它。                                   | 使用真实令牌重新连接。               |
| `需要非空的终端用户 ID。` / `需要非空的终端用户名称。`                                                               | `ConnectWithAuthTokenAsync` 在传入空的 `endUserId` 或 `endUserName` 参数时被调用。              | 请为每次调用传入非空、稳定的账号 ID 和显示名称。                                                                    | 重新连接时请填充这两个参数。            |
| 连接失败，报错 `连接令牌无效` (`ConnectionInvalidToken`)                                                    | Convai 拒绝了令牌——它已过期、格式错误，或者并不是您的端点最近签发的令牌。                                          | 确认您的端点每次请求都返回新签发的令牌，并且没有任何缓存层提供过期的令牌。                                                         | 重新连接；新令牌会被接受。             |
| 连接失败，HTTP `401`                                                                                | room-connect 请求在传输层被拒绝，SDK 将其映射为 `ConnectionInvalidToken`.                         | 确认端点或提供程序返回的是 `apiAuthToken` ——而不是游戏登录令牌、刷新令牌或 Convai 账号 API 密钥——并且该令牌未过期。                    | 重新连接；连接成功。                |
| `在编辑器能够生成身份验证令牌之前，必须先在 Convai 项目设置中保存 API 密钥。`                                                 | 仅限编辑器的回退提供程序尝试运行，但未保存 API 密钥。                                                      | 在以下位置保存 API 密钥： **Convai > Settings > 凭据**，即使在身份验证令牌模式下也是如此，这样编辑器回退也可以在本地生成令牌。                | 再次进入播放模式；回退提供程序会成功。       |
| 身份验证令牌模式在编辑器中可用，但在玩家构建中会立即失败                                                                   | 仅限编辑器的回退提供程序（`ConvaiEditorApiKeyAuthTokenProvider`）一直在静默地替代缺失的提供程序或端点。它不会被编译进玩家版本。 | 注册一个运行时 `IConvaiAuthTokenProvider`，或者配置一个 **令牌端点 URL**，这样玩家构建就有一个真实的凭据来源。                     | 运行构建；连接会在没有编辑器回退的情况下成功。   |
| 在播放模式下更改端点配置不会影响当前会话                                                                           | 凭据在每次连接尝试时只解析一次，而不是持续解析。                                                           | 更改端点、请求头或提供程序后，结束会话并重新连接。                                                                     | 下一次连接尝试会使用更新后的配置。         |

### 端点不是 HTTPS

**症状：** 控制台日志 `身份验证令牌端点必须使用 HTTPS，但本地开发期间使用的 HTTP 回环 URL 除外。`

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

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

**验证：** 重新连接。请求会到达您的服务器，而不是在发送前因校验失败。

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

**症状：** 控制台日志 `未找到身份验证令牌响应字段 'apiAuthToken'。` （或您配置的其他字段名）。

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

**解决方法：** 要么修改服务器，使其在以下位置返回令牌： `apiAuthToken` 作为顶层字段，要么更新 **令牌响应字段** 中的 **Convai > Settings > 凭据** 以匹配您服务器的实际响应结构。

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

### 提供程序注册得太晚

**症状：** 进入播放模式后或构建启动后，首次连接尝试会失败，报错 `Auth Token 模式需要已注册的 IConvaiAuthTokenProvider 或已配置的端点 URL。`，即使您的代码注册了提供程序。

**原因：** `ConvaiAuthTokenProviderRegistry` 是一个进程内的静态注册表，会在以下情况下自动重置： `RuntimeInitializeLoadType.SubsystemRegistration` ——每次域重新加载和每次进入播放模式都会清空它。在 SDK 首次连接尝试之后才初始化的组件中注册的提供程序，或者在重新加载后从未重新注册的提供程序，都会在 SDK 需要时使注册表为空。

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

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

### 未为显式令牌连接选择身份验证令牌模式

**症状：** `ConnectWithAuthTokenAsync` 会立即失败，报错 `显式的身份验证令牌连接需要在 Convai 项目设置中启用 Auth Token 模式。`

**原因：** `RoomConnectionRuntimeAdapter` 会检查当前活动的凭据提供程序是否实现了显式令牌契约，这只有在 **认证模式** 为 **Auth Token**。在以下情况下调用 `ConnectWithAuthTokenAsync` ，而项目仍处于 **API 密钥** 模式时，会在任何网络请求发出之前使此检查失败。

**解决方法：** 将 **认证模式** 到 **Auth Token** 中的 **Convai > Settings > 凭据**。您无需为此路径配置 **令牌端点 URL** ，也无需注册提供程序——调用方会直接提供令牌。

**验证：** 使用以下方式重新连接： `ConnectWithAuthTokenAsync`。调用会继续通过凭据验证，而不会立即失败。

### 连接时出现 HTTP 401

**症状：** room-connect 请求返回 HTTP `401`，SDK 将其报告为 `连接令牌无效` (`ConnectionInvalidToken`).

**原因：** Convai 拒绝了发送在 `API-AUTH-TOKEN` 标头中的令牌。这种情况发生在令牌已过期、已被使用，或者实际上并不是 Convai `apiAuthToken` ——例如，端点或提供程序不小心返回了游戏登录令牌或 Convai 账号 API 密钥。

**解决方法：** 确认您的端点或提供程序返回的是 `apiAuthToken` 字段的值，即 Convai 自己的令牌签发响应中的字段值，而不是其他任何凭据，并且它是为每次连接新签发的，而不是从可能过期的缓存中提供。

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

### 仅限编辑器的回退提供程序未生效

**症状：** 在 Unity 编辑器中，身份验证令牌模式仍然失败，报错 `Auth Token 模式需要已注册的 IConvaiAuthTokenProvider 或已配置的端点 URL。`，尽管已保存 API 密钥。

**原因：** `ConvaiEditorApiKeyAuthTokenProvider` 仅在以下三个条件同时满足时才会自动注册： **认证模式** 为 **Auth Token**，已保存 API 密钥，并且未 **令牌端点 URL** 配置。如果 **令牌端点 URL** 已设置——即使是无效的——回退也不会激活，因为显式端点优先。

**解决方法：** 对于无需真实后端的本地编辑器测试，请清除 **令牌端点 URL** 并确认在以下位置已保存 API 密钥： **Convai > Settings > 凭据**。除编辑器测试外，不要依赖此回退——它不会被编译进任何玩家版本，因此除非配置运行时提供程序或端点，否则构建也会以相同方式失败。参见 [发布安全构建](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/ship-a-secure-build.md).

**验证：** 进入播放模式。编辑器会使用已保存的 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>切换到认证令牌模式，并在项目设置中配置令牌端点。</td><td><a href="/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="/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="/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.