> 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/guide/zh/operation/toss.md).

# 测试迷你应用

上传应用包（.ait）文件后，可以使用生成的测试用 App Scheme 在 Toss App 中进行最终测试。

### 1. 创建应用包文件

应用包是 `.ait` 带有扩展名的文件，是对已构建项目打包后的产物。执行以下命令来生成应用包。构建完成后，在项目根目录中会出现 `<服务名>.ait` 文件。

{% tabs %}
{% tab title="npm" %}

```sh
npm run build
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm build
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn build
```

{% endtab %}
{% endtabs %}

***

### 2. 测试 Toss 应用

将应用包上传并在 Toss 应用中测试的方法有两种。

1. 在控制台直接上传后通过 QR 码测试
2. 通过 CI/CD 命令自动上传

应用包按解压后大小计算，只有 100MB 以下的内容才能上传。如果将图片·声音·视频等资源全部包含进去，可能会超出容量，因此请将资源文件与构建分开管理。

建议这样管理资源。

* 只将应用运行所必需的最少资源包含到包中。
* 请配置为从外部存储或 CDN 下载大容量资源。
* 对额外资源采用逐步下载的方式（Lazy Loading），用户体验会更好。

{% hint style="info" %}
**应用包容量政策**

* 应用包按解压后大小计算，只有 100MB 以下的内容才能上传。
* 如果将资源全部包含进去，可能会超出容量，因此请将资源文件与构建分开管理。
  {% endhint %}

#### 2-1. 在控制台上传应用包后通过 QR 码测试

请先在控制台上传应用包(`.ait`)文件。至少完成 1 次测试后才能请求审核。

> **应用包文件无法上传吗？**
>
> 请确认应用是否已正常构建。 `npm run build`如果不是用该方式生成的包，或者项目结构不正确，应用包编译会失败，因此无法上传。

上传应用包后，点击“测试”按钮，就能在控制台中查看 Toss 应用测试用的 QR 码。扫描 QR 码后，迷你应用会在 Toss 应用中启动。

QR 码测试需满足以下全部条件才能进行。

* 必须已登录 Toss 应用。
* 必须是工作区成员。
* 只有满 19 岁以上的用户才能测试。

<figure><img src="https://1415110023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F7UHLc2xBtRJ3Z66xdaFT%2F%E1%84%87%E1%85%B5%E1%84%80%E1%85%A6%E1%84%8B%E1%85%B5%E1%86%B7%2032.png?alt=media&amp;token=e2471961-74e5-42fe-bab2-26c1384acd42" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1415110023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FUfLbu8Jhp1iMYNz4ZYQV%2F%E1%84%8B%E1%85%B5%E1%84%86%E1%85%B5%E1%84%8C%E1%85%B5.png?alt=media&amp;token=ffe46d48-7b15-40d7-96c4-00f773d1385b" alt=""><figcaption></figcaption></figure>

#### 2-2. 使用 CI/CD 命令

无需登录控制台，也可以通过 CLI 上传应用包。

要通过 CI/CD 命令自动上传，需要 SDK v1.4.0 或更高版本。如果你正在使用更早的版本，请先升级 SDK。

请先在控制台发放 API 密钥。可以按整个应用或特定应用粒度设置访问权限。

> 访问路径：选择工作区 → 左侧菜单中的“密钥”

<figure><img src="https://1415110023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FTRGlSNFN10sqdcSQ4APK%2F%E1%84%8F%E1%85%B5%2065.png?alt=media&amp;token=4683c816-1797-43e2-aafb-6a303e0a5b6f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1415110023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FjOJeYrLClNjd8ioFdl20%2Fimage.png?alt=media&amp;token=51ed417b-f10d-41ae-b047-8e3ca33c54ef" alt=""><figcaption></figcaption></figure>

执行以下命令上传应用包。正常上传后，可以确认测试用的应用 scheme。

```
npx ait deploy --api-key {API 密钥}
```

注册 API 密钥后，就无需反复输入。

```
npx ait token add
npx ait deploy
```

`-m` 在上传包时，可以通过选项顺便留下备注。

```
npx ait deploy -m "发布备注"
```

可根据需要使用以下命令。

| 命令                                              | 用途                            |
| ----------------------------------------------- | ----------------------------- |
| npx ait token --help                            | 查看帮助                          |
| npx ait token add \[工作区名] \[API 密钥]             | 注册令牌                          |
| npx ait token remove \[工作区名]                    | 删除已注册的令牌                      |
| npx ait deploy \[工作区名] \[API 密钥]                | 上传包                           |
| npx ait deploy \[工作区名] \[API 密钥] --timeout \[秒] | 设置部署状态确认的最长等待时间（10秒以上、300秒以下） |

***

### 3. 测试功能

`intoss://` scheme 只有在应用正式发布后才能访问。发布前的功能测试必须使用上传时生成的测试 scheme（QR 码）进行。

#### 在 QR 码中确认 deploymentId

每次上传应用包时，都会生成新的 `deploymentId`。测试 scheme 中的 `_deploymentId`是必填参数。

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

#### 对 scheme 应用 path·query 进行测试

应用子 path 时：

```
intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

应用查询参数时（queryParams 必须进行 URL 编码）：

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22
```

***

### 常见问题

<details>

<summary>iOS 上出现白屏。</summary>

如果在沙盒中运行正常，但在 Toss 应用中出现白屏，请按以下顺序逐项检查。

1. **使用 Sentry 进行错误检测·监控** — 有时会发生运行时错误，却无法立即发现。请用 Sentry 收集错误，追踪真实用户环境中出现的问题。 [Sentry 设置指南](https://developers-apps-in-toss.toss.im/ai-vibe-coding/integration/sentry#id-1.-sentry)
2. **检查内存·资源使用量** — 在 Toss 应用中，由于内存限制，应用可能无法正确渲染并出现白屏。
   * 通过减少图片·字体等资源大小来优化构建文件。
   * 请应用分块加载结构，一开始只加载必需文件，其余资源按顺序逐步加载。
   * 检查是否存在不必要的对象创建或内存泄漏。

</details>

<details>

<summary>在 Toss 应用中无法进行通信。</summary>

* **检查 CORS 设置** — 要让迷你应用与服务器通信，需要在服务器的 CORS 允许 Origin 中添加迷你应用 Origin。需要允许的 Origin 会根据 SDK 版本和适用日期而不同。

{% hint style="info" %}
**SDK 3.x Origin 变更说明**

从 2026 年 8 月 25 日（周二）之后上传的 SDK 3.x 包开始，将使用 SDK 2.x 中使用的 Origin 提供服务。\
如果需要与外部服务器通信，请在服务器的 CORS 允许 Origin 中添加以下 Origin。

* `https://<appName>.apps.tossmini.com` ：正式服务环境
* `https://<appName>.private-apps.tossmini.com` ：控制台 QR 测试环境
  {% endhint %}

SDK 3.x

* `https://<appName>.web.tossmini.com` ：正式服务环境
* `https://<appName>.private-web.tossmini.com` ：控制台 QR 测试环境

\
SDK 1.x \~ 2.x

* `https://<appName>.apps.tossmini.com` ：正式服务环境
* `https://<appName>.private-apps.tossmini.com` ：控制台 QR 测试环境
* **检查 App Transport Security(ATS) 设置** — 沙盒中允许 HTTP 请求，但在正式环境中仅允许 HTTPS。基于 HTTP 的 API 会在 Toss 应用中被阻止。
* **检查 iOS 第三方 Cookie 阻止策略** — 在 iOS·iPadOS 13.4 及以上版本中，第三方 Cookie 会被完全阻止。请改用基于令牌的认证方式，而不是基于 Cookie 的登录。

</details>

<details>

<summary>Toss 应用中无法打开迷你应用。</summary>

在 Toss 应用的旧版本中可能会发生错误，请在最新版本的 Toss 应用中进行测试。

</details>


---

# 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/guide/zh/operation/toss.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.