---
title: "迁移指南：OS 2.1 到 OS 3.0"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/migration-guide-from-os-2-1-to-os-3-0'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/migration-guide-from-os-2-1-to-os-3-0.md'
---
# 迁移指南：OS 2.1 到 OS 3.0
你可以通过本指南了解主题应用扩展 Online Store 2.1 (OS 2.1) 版本和 Online Store 2.1 (OS 3.0) 版本的差异，以及迁移的步骤。

---


## 目录升级{#GBVfX}
OS 2.1 及 OS 3.0 主题应用扩展目录主要差异如下：

| **OS 2.1 目录** | **OS 3.0 目录** |
| --- | --- |
| assets | public |
| locales | i18n |
| snippets | components |


OS 2.1 及 OS 3.0 主题应用扩展目录详情参考：

+ [OS 2.1 版本主题应用扩展目录](https://developer.shopline.com/zh-hans-cn/docs/themes-2-0/integrate-apps-with-themes/theme-app-extension/framework/?version=v20250601)
+ [OS 3.0 版本主题应用扩展目录](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/structure.md?lang=zh-hans-cn)

---


## 语法升级{#Zseai}
| 原语法 | 新语法 |
| --- | --- |
| Handlebars | [Sline](https://developer.shopline.com/zh-hans-cn/docs/sline/object/additional-checkout-buttons.md) |


---

## 迁移步骤{#iskTU}
如果你的现有项目需要升级支持 OS 3.0 主题，可以跟随以下步骤进行升级：

1. 在 `.shopline-cli.yml`文件中新增 `compatibility: true`。

```yaml
---
compatibility: true                   # 新增
project_type: extension
organization_id: 0
EXTENSION_TYPE: THEME_APP_EXTENSION

```

2. 在项目根目录新增 `compatibility`目录，并且将主题应用扩展 OS 2.1 的目录放在此目录内。

```shell
└── theme-app-extension
    ├── blocks
    │   └── ...
    ├── components
    │   └── ...
    ├── i18n
    │   └── ...
    ├── public
    │   └── ...
    ├── compatibility        # 新增
    │   ├── assets
    │   ├── blocks
    │   ├── locales
    │   ├── snippets
    │   └── ...
    └── .shopline-cli.yml
```

3. 废弃 [schema](https://developer.shopline.com/zh-hans-cn/docs/themes-2-0/integrate-apps-with-themes/theme-app-extension/framework?version=v20251201#schema) 内的 `locales` 字段，统一迁移到 `i18n` 目录。

```html
<div>{{ "title" | t() }}</div>

{{#schema}}
{
  ...
  locales: {              # 废弃
    "en": {
      "title": "Title"
    },
    "zh-hans-cn": {
      "title": "标题"
    }
  }
}
{{/schema}}
```

英文内容迁移到 `i18n/en.json`：

```json
{
  "title": "Title"
}
```

中文内容迁移到 `i18n/zh-hans-cn.json`：

```json
{
  "title": "标题"
}
```

4. 安装 [新版本 SHOPLINE CLI](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/development-tools/cli/overview.md) 并使用。

```shell
npm install @shoplineos/cli -g
```