SHOPLINE OS 2.1 到 OS 3.0 迁移指南

这是一项重建，不是版本开关

SHOPLINE Help Center 对 OS 2.1 自定义主题的说明很明确：OS 3.0 使用新的 Sline 模板语法，需要重新开发。迁移同时影响目录结构、应用兼容、多语言配置和 UGC 数据。

合理的项目目标不是“让旧主题文件通过上传”，而是：

1. 在 OS 3.0 结构中重建相同的关键商家与顾客体验。
2. 明确哪些旧能力由平台原生功能替代。
3. 为应用、内容和配置准备可验证的迁移路径。
4. 在发布前保留旧主题和数据回退点。

阶段一：冻结范围并建立清单

先复制或下载当前线上主题，记录版本与日期。随后建立四份清单：

同时记录关键业务流程的当前截图与预期结果，它们会成为迁移后的验收基线。

阶段二：映射目录和责任

官方主题应用扩展迁移指南给出了核心目录变化：

完整主题迁移还需要把旧模块重新归类到 OS 3.0 的 layout、template、section、block 和 component。不要仅用批量重命名完成目录迁移，因为配置 schema 与编辑器行为也发生变化。

阶段三：分批重写模板

推荐顺序：

1. 建立 layout 与全局资源加载。
2. 重建最常用的商品和集合 template。
3. 把可配置内容拆成 section 与 block。
4. 把纯展示复用代码整理为 component。
5. 重写 Sline 对象、标签和过滤器。
6. 最后迁移低访问量页面和边界状态。

每次只迁移一个可单独预览的页面或模块。旧主题中的 Handlebars helper、父级作用域访问与自定义 partial，需要按 Sline 能力重新设计。

阶段四：逐项确认应用兼容

SHOPLINE Help Center 建议先列出所有活跃应用，并确认它们是否支持 OS 3.0。每个应用应有明确状态：

• 已提供 OS 3.0 原生或 theme app extension 方案。
• 可由 OS 3.0 内置功能替代。
• 需要供应商升级。
• 需要自建替代。
• 不再使用，可以移除。

不要在没有兼容结论时直接发布。应用可能改变页面结构、数据字段或用户流程，仅“脚本能加载”不足以证明兼容。

阶段五：迁移多语言

官方主题应用扩展指南要求把旧 schema 中的 locales 内容迁移到 i18n 目录。完整主题还要检查：

• 主市场默认语言。
• 所有可见 section/block 设置。
• 富文本和嵌套结构。
• 图片、链接和语言专属资源。
• 较长翻译是否破坏布局。

迁移后以真实语言切换流程验证，不只检查 JSON 文件存在。

阶段六：迁移 UGC

SHOPLINE Help Center 说明 OS 2.1 的 UGC 需要手动迁移：

1. 在迁移前导出每个 UGC 的 JSON 配置。
2. 在 OS 3.0 重建对应组件结构。
3. 导入配置并重新绑定主题。
4. 对照旧主题检查内容、顺序和交互。

所有导出文件应带有页面、模块和导出日期，避免多个 JSON 文件无法对应。

整理迁移后的模块时，可用 OS 3.0 Sections 概述 复核职责；前台主题信息与诊断证据可通过 Shopline Checker 辅助记录。

阶段七：在测试环境验收

页面状态

• 商品有库存、无库存、多规格和缺图。
• 集合有内容、空集合和分页。
• 顾客未登录、已登录和账户操作。
• 搜索有结果与无结果。
• 不同语言和长文本。

商家编辑

• section 可添加、删除与排序。
• block 嵌套层级符合设计。
• 全局颜色、字体和固定 section 能保存。
• 保存后刷新页面，配置不会丢失。

应用与业务流程

• 应用内容在预期位置显示。
• 加购、购物车、登录和关键营销流程正常。
• 手机与桌面都完成实际操作。
• 控制台没有重复初始化或明显错误。

发布与回退

发布前：

• 保留 OS 2.1 线上主题备份。
• 冻结迁移窗口内的主题内容修改。
• 记录将发布的 OS 3.0 主题版本。
• 明确应用、UGC 和多语言负责人。
• 准备发布后立即执行的冒烟测试。

如果关键交易流程、应用或内容迁移失败，优先恢复已验证的旧主题，再修复 OS 3.0 版本。不要在生产主题上边试边改。

项目完成标准

• 所有关键页面在 OS 3.0 结构中重新实现。
• Handlebars 已重写为可核验的 Sline，不存在伪兼容语法。
• 应用兼容状态全部关闭或有明确替代。
• 多语言字段与 UGC 已迁移并抽样复核。
• 商家编辑器操作与顾客关键流程通过。
• 发布主题有版本记录，旧主题可回退。
• 迁移文档记录了仍未覆盖的非关键差异。