> 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，因此即使在普通浏览器中，60 个以上的 SDK API 和广告流程也会以 mock 方式运行。Production 构建需要真实的 Apps in Toss 应用环境，无法在浏览器中复现。

若要在真机上按生产设置进行确认 `AIT` > `Deploy (Test)`部署后，请用 Apps in Toss 应用扫描弹出窗口中的 QR，或通过 URL 访问。 `ait deploy`始终会部署到控制台 QR 测试环境（`intoss-private://`），因此可通过此流程在正式审核/发布前安全确认。

各配置文件的差异见 [构建配置文件](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`返回了非 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)联系 TechChat。

### 相关文档

* [开始使用](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) — 按配置文件的设置
* [构建流水线](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.