> 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). # 测试迷你应用 ### 1. 创建应用 bundle 文件 应用 bundle 是 `.ait` 扩展名的文件，是将构建完成的项目打包后的产物。请执行以下命令创建应用 bundle。构建完成后，在项目根目录下会生成 `<服务名>.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 App 上传应用 bundle 并在 Toss App 中测试的方法有两种。 1. 从控制台直接上传后，通过 QR 码测试 2. 通过 CI/CD 命令自动上传 应用 bundle 的解压后大小只能上传 100MB 以下。若包含图片、声音、视频等所有资源，可能会超出容量，因此请将资源文件与构建分开管理。 推荐这样管理资源。 * 请仅将应用运行所必需的最少资源包含在 bundle 中。 * 请配置为从外部存储或 CDN 下载大容量资源。 * 如果采用按需逐步下载额外资源的方式（Lazy Loading），用户体验会更好。 {% hint style="info" %} **应用 bundle 容量政策** * 应用 bundle 的解压后大小只能上传 100MB 以下。 * 若将所有资源都包含进去，可能会超出容量，因此请将资源文件与构建分开管理。 {% endhint %} #### 2-1. 在控制台上传应用 bundle 后，通过 QR 码测试 请先将应用 bundle(`.ait`) 文件上传到控制台。至少完成 1 次测试后才能申请审核。 > **应用 bundle 文件无法上传吗？** > > 请确认应用是否已正常构建。 `npm run build`如果不是用……生成的 bundle，或者项目结构不正确，应用 bundle 编译会失败，因此无法上传。 上传应用 bundle 后，点击“测试”按钮，就可以在控制台查看 Toss App 测试用的 QR 码。扫描 QR 码后，迷你应用会在 Toss App 中启动。 QR 码测试需满足以下所有条件。 * 必须已登录 Toss App。 * 必须是工作区成员。 * 只有 19 岁及以上用户才能测试。
#### 2-2. 使用 CI/CD 命令 无需访问控制台，也可以通过 CLI 上传应用 bundle。 要通过 CI/CD 命令自动上传，需要 SDK v1.4.0 以上版本。如果你正在使用旧版本，请先升级 SDK。 请先在控制台发放 API 密钥。可以按整个应用或特定应用单位设置访问权限。 > 访问路径：选择工作区 → 左侧菜单中的“密钥”
执行以下命令上传应用 bundle。上传成功后，可以查看测试用的 app scheme。 ``` npx ait deploy --api-key {API 密钥} ``` 如果提前注册 API 密钥，就无需重复输入。 ``` npx ait token add npx ait deploy ``` `-m` 使用 -m 选项上传 bundle 时，也可以一并留下备注。 ``` npx ait deploy -m "发布备注" ``` 可根据需要使用以下命令。 | 命令 | 用途 | | ------------------------------------------------ | ---------------------------- | | npx ait token --help | 查看帮助 | | npx ait token add \[工作区名称] \[API 密钥] | 注册 token | | npx ait token remove \[工作区名称] | 删除已注册的 token | | npx ait deploy \[工作区名称] \[API 密钥] | 上传 bundle | | npx ait deploy \[工作区名称] \[API 密钥] --timeout \[秒] | 设置部署状态最大等待时间（10 秒以上 300 秒以下） | *** ### 3. 测试功能 `intoss://` 该 scheme 只能在应用正式发布后访问。发布前的功能测试必须使用上传时生成的测试 scheme（QR 码）。 #### 在 QR 码中查看 deploymentId 每次上传应用 bundle 时，都会发放新的 `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 ``` 应用 query 参数后（queryParams 必须进行 URL 编码）： ``` intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22 ``` *** ### 常见问题
iOS 上显示白屏。 如果在 sandbox 中正常运行，但在 Toss App 中出现白屏，请按以下项目顺序检查。 1. **使用 Sentry 进行错误检测·监控** — 运行时发生错误但有时无法立即发现。请通过 Sentry 收集错误，追踪真实用户环境中出现的问题。 [Sentry 设置指南](https://developers-apps-in-toss.toss.im/ai-vibe-coding/integration/sentry#id-1.-sentry) 2. **检查内存·资源使用量** — 在 Toss App 中，由于内存限制，应用可能无法正确渲染并显示白屏。 * 请通过减少图片·字体等资源容量来优化构建文件。 * 请应用分段加载结构，初始仅加载必需文件，其余资源逐步加载。 * 请检查是否存在不必要的对象创建或内存泄漏。
Toss App 中无法通信。 * **检查 CORS 设置** — 若要在迷你应用中与服务器通信，需要在服务器的 CORS 允许 Origin 中添加迷你应用 Origin。需要允许的 Origin 会因 SDK 版本和适用日期而异。 {% hint style="info" %} **SDK 3.x Origin 变更说明** 2026 年 8 月 25 日（周二）之后上传的 SDK 3.x bundle 起，将使用 SDK 2.x 中的 Origin 提供服务。\ 若与外部服务器通信，请在服务器的 CORS 允许 Origin 中添加以下 Origin。 * `https://.apps.tossmini.com` : 实际服务环境 * `https://.private-apps.tossmini.com` : 控制台 QR 测试环境 {% endhint %} SDK 3.x * `https://.web.tossmini.com` : 实际服务环境 * `https://.private-web.tossmini.com` : 控制台 QR 测试环境 \ SDK 1.x \~ 2.x * `https://.apps.tossmini.com` : 实际服务环境 * `https://.private-apps.tossmini.com` : 控制台 QR 测试环境 * **检查 App Transport Security(ATS) 设置** — 沙盒中允许 HTTP 请求，但在正式环境中仅允许 HTTPS。基于 HTTP 的 API 会在 Toss App 中被阻止。 * **检查 iOS 第三方 Cookie 阻止政策** — 在 iOS·iPadOS 13.4 及以上版本中，第三方 Cookie 会被完全阻止。请改用基于 token 的认证方式，而不是基于 Cookie 的登录方式。
Toss App 中无法打开迷你应用。 在 Toss App 的旧版本中可能会发生错误。请在最新版本的 Toss App 中进行测试。
--- # 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=&goal= ``` `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.