# App 命令最佳实践

> 按步骤走一遍旧版 Shoplazza CLI app 命令：准备环境、初始化应用、生成 extension、本地调试，最后部署发布。

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

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

## 前提条件

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

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

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

## 实施步骤

#### 1. 安装或更新 Shoplazza CLI

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

```
npm i -g shoplazza-cli
```

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

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

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

#### 3. 初始化应用项目

```shell
shoplazza app init
```

**初始化过程中：**

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

```shell
# 进入 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. 调试

* 启动本地开发服务器：

```shell
shoplazza app dev  
```

* 命令成功执行后，按照终端提示操作：
  * 按照终端指示输入测试店铺域名。
* 终端返回：（如图所示）

  * App URL
  * Redirect URL
  * Install URL 

  ![](https://cnres.appracle.com/3eaa8e82d56b720c424336cfc9b98338.png)

  
* 进入 Partner 管理后台：

  * 将返回的 App URL 和 Redirect URL 填入 Partner 管理后台的应用设置中。
* ![](https://cnres.appracle.com/3f94baec25c80c1b35de82b12a8480db.jpeg)

  访问 Install URL：

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

  ![](https://cnres.appracle.com/f2a93bffa03b4404dc534ea2c13f596d.png)

  
* 查看效果：

**i. Theme Extension：**

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

***Embed theme extension：***

![](https://cnres.appracle.com/ec807225ac320b242aab2ced6458e161.png)

***Basic theme extension：***

![](https://cnres.appracle.com/10fbeedfdaf8a12d6b9df106c36347ec.png)

**ii. Function Extension：**

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

![](https://cnres.appracle.com/b9cd969c612766e0c3f9e3c538617d67.png)

**iii. Checkout Extension**

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

![](https://cnres.appracle.com/c063b5cea801b10d88ee1d33ebe1e834.png)

#### 6. 部署与发布

**部署应用：**

```shell
shoplazza app deploy
```

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

### 其他技术支持

#### 1. 版本管理

```shell
shoplazza app versions list
```

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

#### 2. 配置管理

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

```shell
shoplazza app config link
```

#### 3. 故障排查

```shell
shoplazza app --help  
shoplazza app <command> --help
```