App 命令最佳实践

本指南提供了如何使用 Shoplazza App CLI 命令来创建、开发和部署 Shoplazza 应用及其 extension 的分步教程。

本文更偏向完整流程示例，适合在第一次搭建应用项目时对照操作。建议您按“准备环境 -> 初始化应用 -> 创建 extension -> 本地调试 -> 部署发布”的顺序阅读；如果只需要查询某个命令的参数或含义，可以先查看 App 命令使用指南中的命令概览。

前提条件

在使用 shoplazza app CLI 命令之前，请确保您的系统已安装以下工具：

1. Node.js（支持版本：v20.9.0 或 v20.18.0）
2. Git
3. 最新版本的 Shoplazza CLI

# 安装或更新 Shoplazza CLI 至最新版本，请运行以下命令：
npm i -g shoplazza-cli

实施步骤

1. 安装或更新 Shoplazza CLI

• 运行以下命令下载或更新 Shoplazza CLI：

npm i -g shoplazza-cli

• 安装完成后，按任意键在浏览器中打开登录页面。

2. 在网页上选择或创建 Partner 账号

浏览器打开登录页面后，选择现有的 Partner 账号或根据需要创建新账号。

3. 初始化应用项目

shoplazza app init

初始化过程中：

• 选择对应的 Organization 账号。
• 选择创建新应用或关联现有应用：
  • 若选择创建新应用：
    • 输入应用名称（例如 your-project）。这将生成项目目录和基本文件结构，包括 shoplazza.app.toml 配置文件。

      my-app/  
      ├── shoplazza.app.toml          # 主配置文件
      ├── shoplazza.app.prod.toml     # 生产环境配置
      ├── shoplazza.app.staging.toml  # 预发布环境配置
      ├── extensions/                 # Extension 目录
      │   ├── theme-extension/        # Theme extension
      │   ├── checkout-extension/     # Checkout extension
      │   └── function-extension/     # Function extension
      ├── package.json  
      └── README.md

4. 创建 App Extension

# 进入 App 项目目录：

cd your-project

# 执行创建 Extension 的命令：

shoplazza app generate extension

• 选择 Extension 类型（Theme / Checkout / Function）
  • 若选择 Theme Extension，您将进一步选择 Theme Extension 的类型：Embed 或 Basic（外部链接）
• 输入 Extension 名称
• 生成 Extension 文件
  Extension 结构示例（extensions/my-extension/）：

  extensions/  
  └── my-extension/  
      ├── shoplazza.extension.toml  # Extension 配置文件
      ├── src/                       # 源代码目录
      │   ├── index.js              # 主入口文件
      │   ├── index.html            # HTML 模板
      │   ├── style.css             # 样式文件
      │   └── script.js             # JavaScript 逻辑
      └── README.md                 # Extension 文档

5. 调试

• 启动本地开发服务器：

shoplazza app dev  

• 命令成功执行后，按照终端提示操作：

  • 按照终端指示输入测试店铺域名。

• 终端返回：（如图所示）

  • App URL
  • Redirect URL
  • Install URL

  

  
  

• 进入 Partner 管理后台：

  • 将返回的 App URL 和 Redirect URL 填入 Partner 管理后台的应用设置中。

• 

  访问 Install URL：

  • 访问 Install URL 进行安装测试。

  

  
  

• 查看效果：

i. Theme Extension：

1. 在店铺管理后台，进入在线商店，然后进入主题编辑器。选择对应的主题，点击编辑进入预览页面。
2. 打开应用管理开关进行 Theme 预览。

Embed theme extension：

Basic theme extension：

ii. Function Extension：

1. 进入在线商店，执行加入购物车操作，观察价格修改脚本是否执行。

iii. Checkout Extension

1. 进入在线商店，导航至结账页面，观察脚本是否已注入。

6. 部署与发布

部署应用：

shoplazza app deploy

1. 检查项目配置和 Extension。创建应用版本。
2. 部署到生产环境：
3. 提供部署结果和预览链接。

其他技术支持

1. 版本管理

shoplazza app versions list

• 使用语义化版本控制（例如 1.0.0、1.1.0、2.0.0）
• 定期查看版本历史：

2. 配置管理

• 为不同环境创建单独的配置文件
• 使用 shoplazza app config use 在环境之间切换
• 定期备份配置文件

shoplazza app config link

3. 故障排查

shoplazza app --help  
shoplazza app <command> --help