测试迷你应用

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

1. 创建应用包文件

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

npm

npm run build

pnpm

pnpm build

yarn

yarn build

---

2. 测试 Toss 应用

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

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

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

建议这样管理资源。

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

应用包容量政策

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

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

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

应用包文件无法上传吗？

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

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

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

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

2-2. 使用 CI/CD 命令

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

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

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

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

执行以下命令上传应用包。正常上传后，可以确认测试用的应用 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

---

常见问题

iOS 上出现白屏。

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

1. 使用 Sentry 进行错误检测·监控 — 有时会发生运行时错误，却无法立即发现。请用 Sentry 收集错误，追踪真实用户环境中出现的问题。 Sentry 设置指南
2. 检查内存·资源使用量 — 在 Toss 应用中，由于内存限制，应用可能无法正确渲染并出现白屏。

   • 通过减少图片·字体等资源大小来优化构建文件。
   • 请应用分块加载结构，一开始只加载必需文件，其余资源按顺序逐步加载。
   • 检查是否存在不必要的对象创建或内存泄漏。

在 Toss 应用中无法进行通信。

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

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 测试环境

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 的登录。

Toss 应用中无法打开迷你应用。

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