> 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/integration/sdk-2.x-qian-yi.md). # SDK 2.x 迁移 SDK 2.x 更新是包含支持 React Native 0.84 和 React 19 的重大更新。\ Toss App 的 React Native 更新已计划进行 **如果使用 SDK 1.x，今后无法保证正常运行。** Apps in Toss 合作伙伴公司 **请务必迁移到 SDK 2.x。** 目前为止 2.x 的最新版本是 `2.10.8` 。 {% hint style="warning" %} 2026年3月23日之后，无法将使用 SDK 1.x 构建的应用包上传到控制台。\ 基于 1.x 的项目将限制新发布和更新。 如果未在期限内更新，可能会另行联系，并可能中止服务运营。 {% endhint %} {% hint style="info" %} **请下载最新 SDK 版本。** 最新 SDK 通常包含以下更改。 * 安全性和稳定性改进 * 新增功能及 API * 修复现有错误并整理已弃用功能 {% endhint %} *** ### 为什么需要迁移？ * React Native 0.72 的安全补丁和维护已结束。 * 2026年3月30日 Toss App 将更新为基于 RN 0.84。 * 运行时和桥接层面不保证与低版本兼容。 * 为了稳定性和安全性，需要使用最新版本。 *** ### 适用对象 如果符合以下情况，需要迁移： * `@apps-in-toss/framework` 使用 1.x 的项目 * `@apps-in-toss/web-framework` 使用 1.x 的项目 * `granite build` 使用该命令的项目 *** ### 变更概要 #### 1. 构建命令将变更 | 原有 | 变更后 | | --------------- | ----------- | | `granite build` | `ait build` | #### 2. React / React Native 版本将更新 | 项目 | 变更前 | 变更后 | | ------------ | ------ | ------ | | React | 18.x | 19.2.3 | | React Native | 0.72.x | 0.84.0 | | Types | 18.x | 19.2.3 | #### 3. 依赖结构将变更 在 SDK 2.x 中，React 和 React Native 版本会更新，并会新应用基于 Granite 的包结构。\ 运行自动迁移命令后，以下变更也会一并反映。 **主要包变更内容** | 包 | 变更前 | 变更后 | | ------------------- | ------ | ------ | | react | 18.x | 19.2.3 | | react-dom | 18.x | 19.2.3 | | react-native | 0.72.x | 0.84.0 | | @types/react | 18.x | 19.2.3 | | @types/react-dom | 18.x | 19.2.3 | | react-test-renderer | 18.x | 19.2.3 | **Granite 相关包** | 包 | 变更前 | 变更后 | | --------------------------------- | --- | ----- | | @granite-js/react-native | - | 1.0.4 | | @granite-js/native | - | 1.0.4 | | @granite-js/plugin-core | - | 1.0.4 | | @granite-js/plugin-env | - | 1.0.4 | | @granite-js/plugin-hermes | - | 1.0.4 | | @granite-js/plugin-router | - | 1.0.4 | | @granite-js/plugin-micro-frontend | - | 1.0.4 | | @granite-js/plugin-sentry | - | 1.0.4 | | babel-preset-granite | - | 1.0.3 | | @toss/tds-react-native | - | 2.0.2 | | brick-module | - | 0.5.0 | *** ### WebView 迁移 #### 1. 请将框架更新到 2.x `@apps-in-toss/web-framework`的版本 **2.x**请更新。 ```bash # npm npm install @apps-in-toss/web-framework@2.10.8 # yarn yarn add @apps-in-toss/web-framework@2.10.8 # pnpm pnpm add @apps-in-toss/web-framework@2.10.8 ``` #### 2. 请修改构建命令 | 原有 | 变更后 | | --------------- | ----------- | | `granite build` | `ait build` | *** ### React Native 迁移 #### 1. 请将框架更新到 2.x 版本 `@apps-in-toss/framework`的版本 **2.x**请更新。 ```bash # npm npm install @apps-in-toss/framework@2.10.8 # yarn yarn add @apps-in-toss/framework@2.10.8 # pnpm pnpm add @apps-in-toss/framework@2.10.8 ``` #### 2. 请运行自动迁移 ```bash # npx npx ait migrate react-native-0-84-0 # yarn yarn ait migrate react-native-0-84-0 # pnpm pnpm ait migrate react-native-0-84-0 ``` 以下项目会自动反映： * `package.json` 依赖版本更新 * `babel.config.js` 设置更新 * `granite build` → `ait build` 变更后 #### 3. 请确认类型错误 升级到 React 19 和 React Native 0.84 后，部分类型定义已发生变化。 迁移后请务必确认以下项目： * `React.FC` 相关类型错误 * `children` 类型定义变更 * 与 React 19 新 API 是否冲突 * Strict Mode 相关警告 [React 19 升级指南文档](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)请参考。 *** ### 测试指南 * 为了应对 RN 0.84 **于 2026年3月6日上传的最新沙盒应用已发布。** * 务必 **请使用 3月6日上传版本及以上的沙盒应用进行测试。** [下载最新沙盒应用](/landing-page/landing-page-zh/development/test/sandbox.md) > 在当前 Toss App 环境下无法进行 RN 0.84 对应测试。\ > 请务必在沙盒应用中测试。 旧版沙盒应用中，RN 0.84 环境验证可能无法正常进行。\ 测试前请务必确认沙盒应用版本。 *** ### 迁移检查清单 * [ ] 已更新到 SDK 2.x * [ ] `ait migrate react-native-0-84-0`已执行 * [ ] 已修复所有类型错误 * [ ] `ait build`构建可正常运行 * [ ] 已在最新沙盒环境中完成测试 *** ### 常见问题 我们整理了有关切换到 SDK 2.x 时经常收到的咨询。 #### 📌 政策及切换日程相关 **Q. 如果继续使用 SDK 1.x，会怎样？** 在 Toss App RN 0.84 更新之后，无法保证正常运行。\ 2026年3月23日之后，无法将基于 1.x 构建的包上传到控制台。 如果未遵守期限，可能会另行联系并中止服务运营。 **Q. 之前已发布的应用也需要迁移吗？** 是的，之前已发布的应用也需要更新到 SDK 2.10.8。\ 3月23日之后，将无法基于 SDK 1.x 进行新发布及更新。 **Q. 3月23日之后，现有用户会怎样？** 已发布的基于 1.x 的迷你应用会继续按原版本运行。\ 不过，无法进行新更新。 **Q. 没有更新 Toss App 的用户会怎样？** 没有更新 Toss App 的用户将继续在现有基于 RN 0.72 的环境中使用服务。\ 内部预计到 5月底将有 80\~90% 以上的用户完成迁移。 **Q. 有 Toss App 强制更新计划吗？** 如果 5 月之后更新比例仍然较低，我们会考虑强制更新。\ 具体日程确定后会另行通知。 **Q. 迷你应用本身可以加入旧版本屏蔽逻辑吗？** 可以。\ 也允许通过远程控制方式加入屏蔽特定版本以下的逻辑。 **Q. 想了解快速切换到 RN 0.84 的背景。** 内部已长期进行准备，\ 并已在内部完成 RN 0.84 与主要第三方库的兼容性测试。 在分阶段验证后确认稳定性，才决定切换。 #### 🧪 测试及发布相关 **Q. 应用了 RN 0.84 的 Toss App 不能在外部测试吗？** 目前应用了 RN 0.84 的 Toss App 不提供外部测试用版本。\ 合作伙伴请在最新沙盒应用中测试。 已提交的包在内部审核阶段会在 RN 0.72 / 0.84 Toss App 环境下进行 Android / iOS 测试。 **Q. 什么时候提交审查请求？** 如果沙盒测试和 Toss App QR 测试都没有问题，请立即提交审查请求。\ 收到审查请求后，内部也会在 RN 0.84 Toss App 环境中进行额外验证。 **Q. 应用了 RN 0.84 的 Toss App 什么时候会分发给用户？** 将从 3月30日开始逐步分发。\ 由于不是强制更新，更新时间可能会因用户设置而不同。 内部预计到 5月底将有 80\~90% 完成迁移。 **Q. WebView 也必须升级到 React 19 吗？** 不是的。\ 只有 React Native 迷你应用必须更新到 React 19。\ WebView 迷你应用保持 React 18.x 也可以。 **Q. 不提供仅供 SDK 1.x 的沙盒应用吗？** 不会提供单独的仅供 SDK 1.x(0.72) 的沙盒应用。\ 最新沙盒应用不支持基于 SDK 1.x 的迷你应用测试。 请务必更新到 SDK 2.x 后，在最新沙盒应用中测试。 #### 🛠 技术问题及问题解决 **Q. 自动迁移后仍然报错。** 由于 React 19 和 RN 0.84 的变更，可能需要部分手动修正。\ 请检查构建日志并解决类型及依赖冲突。 **Q. 在进行 SDK 2.10.8 迁移后出现 StackOverflowError。** 通常是由于 Metro 服务器连接问题导致。\ `adb reverse tcp:8081 tcp:8081` 请确认该命令是否正常工作。 **Q. iOS 沙盒中连接 8081 端口时发生错误。** 目前在部分环境中连接 8081 端口时会发生错误，正在修复中。\ 请先使用基于 IP 的连接进行测试。 **Q. 无法登录最新沙盒应用。** 请确认以下两点： 1. 确认控制台登录账号及密码是否过期\ 如果控制台账号没有问题，请通过 Channel Talk 咨询。 2. 确认 Metro 服务器连接状态 *** ### 咨询 关于迁移的咨询，请通过 Channel Talk 或社区联系我们。 --- # 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/integration/sdk-2.x-qian-yi.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.