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删除后再重新构建试试。

构建各阶段会发生什么， 构建流水线已整理在其中。

应用设置不正确的错误

AIT > Configuration请确认是否已在其中创建了设置资源。该错误会在找不到设置资源本身时出现。

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

运行异常时

在 Unity Editor 中只出现 Mock 日志

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

实际行为请通过 WebGL 构建后在 Apps in Toss 应用中确认。详情请参见 API 使用模式 文档中的 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://），因此可通过此流程在正式审核/发布前安全确认。

各配置文件的差异见 构建配置文件。

（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 应用版本。

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

错误处理模式全般请参见 API 使用模式。

卡在加载画面

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

处理加载画面本身的方法见 加载画面自定义。

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

在 Unity 6000.1.8 以下版本中，2D 物理引擎（Rigidbody2D）时，WebGL 构建中 GC 内存不会释放而是持续累积，这是一个已知问题。详情请参见 Unity Discussions 论坛。

解决方法: 请使用 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在其中进行。

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

false仅在你现在能明确断定确实无法发放该商品时才返回。"既然不确定，那就先 false这样做" 的应用会在每次支付时都弹出这个页面。

恢复已失败的订单: 由此现象 true 未收到响应的订单会保持发放失败状态。 IAPGetPendingOrders查询后 IAPCompleteProductGrant完成发放。已获批准但发放遗漏的订单请用 IAPGetCompletedOrRefundedOrders查找。

重要: 详细机制和完整代码请参见 API 使用模式 文档中的 内购：发放批准与服务器验证 部分。立即批准、 onEvent 验证、应用启动时对白——这三者是一组，不能只单独使用其中一个。

开发环境

看不到 AIT 菜单

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

如果仍未解决

1. 请获取 Unity Console 的完整错误信息。
2. 请同时查看浏览器开发者工具的 Console 和 Network 选项卡。
3. GitHub Issue提交，或 TechChat联系 TechChat。

相关文档

• 开始使用 — 安装与基本设置
• API 使用模式 — 异步模式与错误处理
• 构建配置文件 — 按配置文件的设置
• 构建流水线 — 构建阶段与错误代码
• 贡献指南 — 修改 SDK 本身时