SDK 3.x 迁移

localStorage 使用时请暂时暂停迁移。

在 SDK 2.x 中的浏览器 localStorage如果直接使用，迁移到 SDK 3.x 后将无法访问现有 localStorage 数据。

如果需要保留现有数据，请在另行通知前暂停 SDK 3.x 迁移。

@apps-in-toss/web-framework由其提供的 存储 API，或者如果正在使用现有 localStorage 数据且不需要保留，可以正常迁移。

SDK 3.x 是对 WebView 项目结构进行改进的更新。 配置文件名称和部分属性发生了变化，客户端 SDK 也得到了升级。 参数和返回值与 SDK 2.x 保持一致，并将 SDK 内部处理逻辑从客户端改为在服务器端处理。

即使发生 SDK 问题，也无需合作伙伴重新发布，只需在 Apps in Toss 服务器上修改并应用即可。 SDK 3.x 是为了提升 mini app 生态的稳定性，并将 SDK 保持为稳定版本。

---

变更概要

项目	变更前	变更后
配置文件名称	granite.config.ts	apps-in-toss.config.ts
brand 设置	displayName, primaryColor, icon 包含	primaryColor仅保留
webViewProps	类型 包含属性	webView重命名为， 类型 删除
outdir	outdir	webBundleDir
web 设置	在配置文件中 web.commands 包含	删除后 package.json迁移到
测试环境	需要安装并登录沙盒应用	可直接通过本地浏览器（AIT Devtools）测试

---

更新包

先 @apps-in-toss/web-framework升级到 3.x 版本。

npm

npm install @apps-in-toss/web-framework

yarn

yarn add @apps-in-toss/web-framework

pnpm

pnpm add @apps-in-toss/web-framework

如果使用 TDS(Toss Design System)，请将以下两个包更新到 2.4.1 版本。

• @toss/tds-mobile
• @toss/tds-mobile-ait

npm

npm install @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

yarn

yarn add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

pnpm

pnpm add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

---

自动迁移

执行以下命令后，配置文件转换和 package.json 脚本更新会自动处理。

npx

npx ait migrate v3

yarn

yarn ait migrate v3

pnpm

pnpm ait migrate v3

执行后 apps-in-toss.config.ts 会生成文件， package.json中 dev, build 脚本会更新。 迁移完成后，请确认 mini app 在本地浏览器中是否正常运行。

---

手动迁移

apps-in-toss.config.ts如果未生成或值不正确，请查看手动迁移指南。

1. 更改配置文件名称

granite.config.ts 将文件名 apps-in-toss.config.ts更改为。

2. brand 整理配置

brand 在配置中 primaryColor删除除其以外的其余属性。

// 变更前
brand: {
  displayName: '应用名称',
  primaryColor: '#3182F6',
  icon: 'https://...',
},

// 变更后
brand: {
  primaryColor: '#3182F6',
},

3. webViewProps → webView更改为

webViewProps的名称 webView改为， 类型 删除该属性。

// 变更前
webViewProps: {
  type: 'partner',
},

// 变更后
webView: {},

4. outdir → webBundleDir更改为

// 变更前
outdir: 'dist',

// 变更后
webBundleDir: 'dist',

5. web 删除配置后 package.json迁移到

web 删除配置块，并将 web.commands中的命令 package.json迁移到

• web.commands.dev → package.json中 dev 直接迁移到脚本中。
• web.commands.build → package.json中 build 迁移到脚本中， ait build并一并执行。

// package.json 更改示例
{
  "scripts": {
    "dev": "vite --port 3000",
    "build": "vite build && ait build"
  }
}

---

变更前后示例

变更前(granite.config.ts)

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'my-app',
  brand: {
    displayName: '我的应用',
    primaryColor: '#3182F6',
    icon: 'https://...',
  },
  web: {
    host: 'localhost',
    port: 3000,
    commands: {
      dev: 'vite --port 3000',
      build: 'vite build',
    },
  },
  webViewProps: {
    type: 'partner',
  },
  permissions: [],
  outdir: 'dist',
});

变更后(apps-in-toss.config.ts)

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'my-app',
  brand: {
    primaryColor: '#3182F6',
  },
  webView: {},
  permissions: [],
  webBundleDir: 'dist',
});

---

注意事项

1. SDK 3.x 发布后无法回滚

发布已应用 SDK 3.x 及以上版本的应用包后，无法回滚到 SDK 2.x 版本。 请充分通过二维码测试后再发布。

2. CORS 会变更

从 SDK 3.x 版本开始，CORS(Cross-Origin Resource Sharing) 将变更为如下所示。 如果未在 Origin 允许列表中注册以下域名，API 请求可能会被阻止。请在 Origin 允许列表中注册以下域名。

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

3. 将提供新的测试环境

以前需要安装并登录沙盒应用，而且每次沙盒应用更新时都要重新更新，比较麻烦。 从 SDK 3.x 开始，无需这一过程，只要打开本地浏览器即可直接测试。 设置方法请参考下面的测试环境。

---

测试环境

如果是新项目脚手架生成，或者已从 2.x 迁移到 3.x，则会自动配置 AIT Devtools。

可通过以下命令直接在本地浏览器中确认。 请在本地浏览器中打开 localhost 链接，确认 mini app 是否正常运行。

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

测试环境手动设置

如果是从 SDK 3.0.1 版本迁移，则需要手动配置 AIT Devtools。 请按照以下步骤进行设置。

1. 安装包

npm

npm install -D @apps-in-toss/devtools

pnpm

pnpm add -D @apps-in-toss/devtools

yarn

yarn add -D @apps-in-toss/devtools

2. 打包器设置

如果使用 Vite vite.config.ts请在其中添加 Devtools 插件。

如果使用其他打包器， @apps-in-toss/devtools/unplugin提供的对应打包器适配器添加到配置文件中。例如 aitDevtools.vite(), aitDevtools.webpack()可以这样使用。

下面的代码是使用 Vite 打包器时的配置示例。

import aitDevtools from "@apps-in-toss/devtools/unplugin";

export default defineConfig({
  plugins: [
    aitDevtools.vite(),
    react(),
    babel({ presets: [reactCompilerPreset()] }),
  ],
});

3. 测试

启动服务后，通过本地浏览器访问。如果右下角能看到 AIT Devtools，说明已正常配置，可以直接在此界面测试 mini app 的运行。

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

迁移检查清单

• granite.config.ts将 apps-in-toss.config.ts重命名为
• brand中 primaryColor只保留，其他已删除
• webViewProps将 webView更改为 类型已删除
• outdir将 webBundleDir更改为
• web 删除设置并将命令 package.json迁移到
• build 脚本中 ait build已包含
• 构建正常运行
• 已在测试环境(AIT Devtools)中确认正常运行
• 已将 bundle 上传到 Apps in Toss 控制台
• 已在 Toss App 中完成测试

---

咨询

有关迁移的问题，请通过 Channel Talk 或社区咨询。