> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/unity/first-steps/faq.md).

# FAQ

这是使用 SDK 时经常卡住的地方及其解决方法。请按症状查找。

### 无法构建时

#### 找不到 Node.js 的错误

构建流水线使用 Node.js。即使系统中未安装，SDK 也会自动下载内置的 Node.js，所以如果出现下载对话框，直接下载即可。

内置 Node.js 会保存在如下位置。路径中会按层级附加 Node 版本和平台。

```
macOS/Linux   ~/.ait-unity-sdk/nodejs/v<版本>/<平台>/
Windows       %LOCALAPPDATA%\ait-unity-sdk\nodejs\v<版本>\<平台>\
```

如果还是持续出现找不到的错误， `~/.ait-unity-sdk/nodejs`整个删除后重新构建。大多是因为下载中断导致文件损坏。

#### Unity WebGL 构建失败

1. **Unity 版本** — 至少需要 2021.3。推荐 Unity 6 及以上。
2. **未安装 WebGL 模块** — 请在 Unity Hub 中安装 WebGL Build Support 模块。
3. **内存不足** — 请重启 Unity Editor，关闭其他程序后再试。

Console 窗口中的编译错误和堆栈跟踪是最确凿的线索。

#### 依赖安装失败

构建流水线使用 pnpm。 `不是 npm。`。

1. **网络** — 请检查互联网连接；如果是代理环境，也请检查代理设置。
2. **损坏的 node\_modules** — `ait-build/node_modules`删除后重新构建。
3. **尝试直接执行** — `ait-build` 目录中 `pnpm install`的话，可以看到比 Unity Console 更详细的错误。

#### granite 构建失败

这是在打包阶段失败的情况。

1. **TypeScript 编译错误** — `BuildConfig~/`中添加的用户代码存在语法错误，请检查。
2. **依赖冲突** — `package.json`中添加的包版本，请检查， `node_modules`删掉后再试着重新构建。

构建各阶段会发生什么， [构建流水线](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process)中有整理。

#### 应用设置不正确的错误

`AIT` > `Configuration`中是否已创建设置资产。此错误是在找不到设置资产本身时出现的。

> **参考**：必填项只有 **应用 ID 一个**。在设置窗口中， `*`后面带有标记的项目也只有应用 ID。图标 URL 是可选项，仅在输入时才会检查是否 `http://` 或 `https://`开头的格式。留空也可以继续构建。

### 运行异常时

#### Unity Editor 里只显示 Mock 日志

这是正常行为。SDK API 只有在 WebGL 构建中才会真正走桥接。在 Editor 中， `[AIT Mock] <API> called` 会记录日志并返回默认值。

请构建为 WebGL 并在 Apps in Toss 应用中确认实际行为。更多内容请参见 [API 使用模式](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) 文档的 **Mock** 部分。

#### 在 Dev Server 可以，但在 Production 不行

Dev Server 开启了 devtools，因此在普通浏览器中也能以 mock 方式运行 60 多个 SDK API 和广告流程。Production 构建需要真实的 Apps in Toss 应用环境，无法在浏览器中复现。

如果想按生产设置在真机上确认， `AIT` > `Deploy (Test)`部署后，扫描弹出窗口中的 QR 码，使用 Apps in Toss 应用打开，或通过 URL 访问。 `ait deploy`总是部署到控制台 QR 测试环境（`intoss-private://`），因此可以通过这个步骤在正式审核、发布前安全确认。

按 profile 有哪些不同， [构建配置文件](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles)中有说明。

#### （3.x 以前用户） `Production Server` 菜单消失

从 SDK 3.0.0 开始，由于无法再通过将本地服务器连接到单独的沙盒应用进行测试， `AIT` > `Production Server` 菜单不再存在。若要在真机上确认生产设置，请按上面“在 Dev Server 可以，但在 Production 不行”项的 `Deploy (Test)`来做。

由于同样的改版， `AIT` > `Publish` 菜单也 `Deploy (Test)`（增量构建，memo `[Test]`）和 `Deploy (Production)`（清理构建，memo `[Production]`）被拆分了。 `ait deploy` CLI 本身会始终把这两个菜单都部署到控制台 QR 测试环境，真正发布是 `Deploy (Production)`在部署后通过弹出的“打开控制台”按钮跳转到控制台，在那里申请审核后才会进行。

#### 发生 AITException

1. `ErrorCode`和 `Message`请一并确认。
2. `IsPlatformUnavailable`如果是 `true`，那不是代码问题，而是运行环境问题——没有触达桥接。
3. 请检查网络状态和 Apps in Toss 应用版本。

```csharp
try
{
    var result = await AIT.SomeAPI();
}
catch (AITException ex)
{
    Debug.LogError($"错误代码：{ex.ErrorCode}，消息：{ex.Message}");
}
```

关于错误处理模式的整体内容， [API 使用模式](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)中有说明。

#### 卡在加载画面

1. **Unity 初始化失败** — 请在浏览器开发者工具的 Console 标签中确认错误。
2. **资源加载失败** — 请在 Network 标签中确认失败的请求和 CORS 设置。
3. **内存不足** — 在移动端请关闭其他应用后再试。

关于如何处理加载画面本身， [加载画面自定义](https://developers-apps-in-toss.toss.im/documentation/unity/build/loading-screen-customization)中有说明。

#### WebGL 构建中的内存占用持续增加（使用 Rigidbody2D 时）

在 Unity 6000.1.8 以下版本中，使用 2D 物理引擎（`Rigidbody2D`）时，WebGL 构建中会出现 GC 内存不释放并持续累积的已知问题。详情请参见 [Unity Discussions 论坛](https://discussions.unity.com/t/memory-leak-when-using-rigidbody2d-physics-in-webgl/1649803)。

**解决方法**：请使用 Unity 6000.1.8 及以上版本。

#### 支付 API 不工作

1. **Mock 环境** — 实际支付只能在 Apps in Toss 应用内运行。
2. **缺少选项** — 请确认所有必填字段都已填写。尤其是订单创建 API 必须 `ProcessProductGrant`指定（见下方项目）。

### 内购后显示退款说明页面

支付成功了，但是 `{应用名称}出了问题。请申请退款` 页面出现，且商品未发放。

`ProcessProductGrant` 回调返回了 `true`而不是值。大多数情况下是因为回调 **根本没有设置** 的情况，此时 SDK 因为没有注册的处理器，会自动 `false`并在 Console 中留下如下错误。

```
[AITCore] Nested callback 'processProductGrant' is not registered
```

即使直接 `false`返回，也会显示同样的页面。

**解决方法**：请设置回调并立即 `true`返回。返回类型是 `bool`，因此在这里进行服务器验证（`await`）本来就无法编译。验证和发放应在覆盖层关闭后于 `onEvent`中进行。

```csharp
// ✅ 立即批准回调，并在 onEvent 中进行验证与发放
options.ProcessProductGrant = _ => true;
// ...
onEvent: e => { ShowPurchaseSuccess(); _ = MyServer.VerifyAndDeliver(e.Data.OrderId); }
```

`false`只有在你现在就能确定真的无法发放该商品时才返回。"我没把握，所以先 `false`"——这样会变成每次支付都出现此页面的应用。

**恢复已失败的订单**：出现该症状时 `true` 没有收到响应的订单会保持为发放失败状态。 `IAPGetPendingOrders`查询后， `IAPCompleteProductGrant`完成发放。已批准但发放漏掉的订单可通过 `IAPGetCompletedOrRefundedOrders`查找。

> **重要**：详细机制和完整代码请参见 [API 使用模式](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) 文档的 **内购：发放批准与服务器验证** 部分。立即批准、 `onEvent` 验证、应用启动时对话——这三者是一个整体，不能只单独拿出其中一个使用。

### 开发环境

#### 看不到 AIT 菜单

1. **包安装失败** — `Window` > `Package Manager`中确认 SDK 是否已安装，如果有错误，请删除后重新安装。
2. **编译错误** — 只要 Console 中有任何一个编译错误，菜单就不会注册。请全部解决后重启 Unity。
3. **Unity 版本** — 请确认是否为 2021.3 及以上。

### 如果还是无法解决，

1. 请获取 Unity Console 的完整错误消息。
2. 请同时查看浏览器开发者工具的 Console 和 Network 标签。
3. [提交 GitHub issue](https://github.com/toss/apps-in-toss-unity-sdk/issues)或 [TechChat](https://techchat-apps-in-toss.toss.im)联系。

### 相关文档

* [开始使用](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/getting-started) — 安装与基础设置
* [API 使用模式](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) — 异步模式与错误处理
* [构建配置文件](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles) — 按 profile 的设置
* [构建流水线](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process) — 构建阶段与错误代码
* [贡献指南](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Documentation~/Contributing.md) — 修改 SDK 本身时


---

# 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://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/unity/first-steps/faq.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.