> 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-3.x-qian-yi.md).

# SDK 3.x 迁移

{% hint style="info" %}
 **`localStorage` 使用时请暂时搁置迁移。**

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

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

`@apps-in-toss/web-framework`提供的 `Storage` API，或正在使用现有 `localStorage` 如果不需要保留数据，可以正常迁移。
{% endhint %}

SDK 3.x 是对 WebView 项目结构进行优化的更新。\
配置文件名称和部分属性有所变更，客户端 SDK 也得到了升级。\
参数和返回值与 SDK 2.x 相同，并且将 SDK 内部处理逻辑改为由服务器而不是客户端处理。

即使出现 SDK 问题，也无需合作方重新发布，只需在 App in Toss 服务器上修改并生效。\
SDK 3.x 的目的是提高小程序生态的稳定性，并将 SDK 维持在稳定版本。

***

### 变更摘要

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

***

### 更新包

首先 `@apps-in-toss/web-framework`将更新到 3.x 版本。

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

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

如果使用 TDS（Toss Design System），请将下面两项更新到 2.4.1 版本。

* `@toss/tds-mobile`
* `@toss/tds-mobile-ait`

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

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

***

### 自动迁移

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

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

```sh
npx ait migrate v3
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn ait migrate v3
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm ait migrate v3
```

{% endtab %}
{% endtabs %}

执行后 `apps-in-toss.config.ts` 会生成文件，并且 `package.json`的 `dev`, `build` 脚本会更新。\
迁移完成后，请确认小程序在本地浏览器中能否正常运行。

***

### 手动迁移

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

#### 1. 更改配置文件名称

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

#### 2. `brand` 整理配置

`brand` 在配置中 `primaryColor`删除除该项之外的其余属性。

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

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

#### 3. `webViewProps` → `webView`改为

`webViewProps`的名称 `webView`更改为 `type` 并删除属性。

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

// 变更后
webView: {},
```

#### 4. `outdir` → `webBundleDir`改为

```ts
// 变更前
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`一起执行。

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

***

### 变更前后示例

#### 变更前(granite.config.ts)

```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)

```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` ：控制台二维码测试环境

#### 3. 提供新的测试环境

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

***

### 测试环境

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

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

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

```shellscript
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```shellscript
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```shellscript
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 测试环境手动设置

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

#### 1. 安装包

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

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}
{% endtabs %}

#### 2. 打包器设置

使用 Vite 时 `vite.config.ts`中添加 Devtools 插件。

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

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

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

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

#### 3. 测试

启动服务后，通过本地浏览器访问。如果右下角能看到 AIT Devtools，说明设置正常，可以在此界面直接测试小程序运行情况。

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

```shellscript
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```shellscript
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```shellscript
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 迁移检查清单

* [ ] `granite.config.ts`将 `apps-in-toss.config.ts`重命名为
* [ ] `brand`在 `primaryColor`仅保留并删除其余内容
* [ ] `webViewProps`将 `webView`改为并 `type`已删除
* [ ] `outdir`将 `webBundleDir`改为
* [ ] `web` 删除配置并将命令 `package.json`移到
* [ ] `build` 在脚本中 `ait build`已包含
* [ ] 构建可正常运行
* [ ] 已在测试环境（AIT Devtools）中确认正常运行
* [ ] 已向 App in Toss 控制台上传包
* [ ] 已在 Toss 应用中完成测试

***

### 咨询

关于迁移的咨询，请通过 ChannelTalk 或社区联系我们。


---

# 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-3.x-qian-yi.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.