# 概述

**shoplazza app 命令**是 Shoplazza CLI 中的核心命令组，专为开发和管理 Shoplazza 应用而设计。它为整个应用开发生命周期提供全面支持，从项目**初始化**到**部署**和**发布**。

本页按命令维度介绍 `shoplazza app` 的用法，适合在开发过程中快速确认某个命令的作用、使用场景和示例。首次创建项目时，建议先阅读命令概览，再根据当前阶段进入 `init`、`generate extension`、`dev` 或 `deploy` 等具体小节。

## 前提条件

在使用 **shoplazza app 命令**之前，请确保您已：

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

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

## App 命令概览

|
命令

 |

功能说明

 |

使用场景

 |
| --- | --- | --- |
|

[shoplazza app init](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#app-init)

 |

初始化新应用项目

 |

创建新应用项目，
或连接现有应用项目。

 |
|

[shoplazza app generate extension](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#generate-extension)

 |

生成 extension template

 |

为现有应用添加新 extension

 |
|

[shoplazza app dev](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#dev)

 |

启动本地开发服务器

 |

本地开发与调试

 |
|

[shoplazza app deploy](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#deploy)

 |

将应用部署到
生产环境

 |

将应用发布到生产环境。

 |
|

[shoplazza app config link](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#config-link)

 |

链接应用配置文件

 |

将现有应用连接到本地项目

 |
|

[shoplazza app config use](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#config-use)

 |

切换应用配置文件

 |

在多个应用配置之间切换

 |
|

[shoplazza app versions list](/zh-CN/docs/app/developer-tools/shoplazza-cli/app-command/#versions-list)

 |

查看应用版本列表

 |

管理应用版本历史

 |

## App 命令详情

### `shoplazza app init` - 初始化应用项目

**功能：**

*   创建新的 Shoplazza 应用项目，包括项目模板和配置文件。或连接现有应用项目。

**使用场景：**

*   开始开发新的 Shoplazza 应用，从零创建应用项目
*   连接到现有应用项目

**命令格式：**

```shell
shoplazza app init [options]
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目创建路径（默认：当前目录） |
| `--client-id <client-id>` | 指定要连接的现有应用的 client ID |
| `--name <name>` | 指定应用名称 |

**使用示例：**

```shell
# 在当前目录创建新应用：
shoplazza app init

# 在指定目录创建新应用：
shoplazza app init --path ./my-new-app

# 创建具有指定名称的新应用：
shoplazza app init --name "your_app_name"

# 连接到现有应用：
shoplazza app init --client-id your-client-id
```

### `shoplazza app generate extension` - 生成 Extension Template

**功能：**

*   为现有应用生成新的 extension template，支持多种 extension 类型。
    **使用场景：**
*   为现有应用添加新功能
*   创建 theme extension、checkout extension 或 function extension

**命令格式：**

```shell
shoplazza app generate extension [options]
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目路径（默认：当前目录） |

**支持的 Extension 类型**：

*   _**[Theme Extension](/zh-CN/docs/app/extensions/online-store/)**_：
    提供扩展和自定义 theme 页面的方式，与在线商店主题集成。Theme App Extension 可替代使用 Script 将应用与在线商店集成的方式。
*   _**[Checkout Extension](/zh-CN/docs/app/extensions/checkout/)**_：
    允许开发者自定义结账页面，包括隐藏特定模块、修改商品信息、地址详情、配送信息、支付详情和订单结果信息，还可插入自定义内容。
*   _**Function Extension**_：
    允许开发者定义自定义逻辑来计算购物车价格。当 cart-transform function 绑定到购物车价格修改点时，Shoplazza 会在购物车或结账阶段自动执行绑定的 function 代码，通过更新操作动态调整定价策略。

**使用示例：**

```shell
# 在当前项目中生成新 extension：
shoplazza app generate extension

# 在指定项目中生成新 extension：
shoplazza app generate extension --path ./my-app
```

### `shoplazza app dev` - 本地开发

**功能：**

*   启动本地开发服务器

**使用场景：**

*   应用的本地开发与调试
*   测试 extension 功能

**命令格式：**

```shell
shoplazza app dev
```

**参数**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目路径（默认：当前目录） |

### `shoplazza app deploy` - 部署应用

**功能：**

*   将应用部署到生产环境，使其在 Shoplazza Store 中上线。

**使用场景：**

*   将已完成的应用发布到生产环境
*   更新现有应用版本

**命令格式：**

```text
shoplazza app deploy [options]
```

**参数**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目路径（默认：当前目录） |

**使用示例：**

```shell
# 部署应用：
shoplazza app deploy

# 部署指定项目：
shoplazza app deploy --path ./my-app
```

### `shoplazza app config link` - 链接应用配置

**功能：**

*   将现有 Shoplazza 应用链接到本地项目，创建配置文件。

**使用场景：**

*   将现有应用连接到本地开发环境
*   为现有应用创建本地配置文件
*   在本地项目中管理多个应用配置

**命令格式：**

```shell
shoplazza app config link [options]
```

**参数**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目路径（默认：当前目录） |
| `--client-id <client-id>` | 指定要链接的应用的 client ID |

**使用示例：**

```shell
# 链接应用配置：
shoplazza app config link

# 链接指定应用：
shoplazza app config link --client-id your-client-id

# 在指定目录中链接：
shoplazza app config link --path ./my-project
```

### shoplazza app config use - 切换应用配置

**功能：**

*   在项目中的多个应用配置文件之间切换，激活指定配置。

**使用场景：**

*   在项目中管理多个应用配置
*   在不同应用之间切换进行开发

**命令格式：**

```shell
shoplazza app config use [options]
```

**参数**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目路径（默认：当前目录） |

**使用示例：**

```shell
# 切换应用配置：
shoplazza app config use

# 在指定项目中切换配置：
shoplazza app config use --path ./my-project
```

### `shoplazza app versions list` - 查看应用版本

**功能：**

*   查看应用所有已部署版本，支持分页和详细信息展示。

**使用场景：**

*   查看应用版本历史
*   了解版本部署状态

**命令格式：**

```shell
shoplazza app versions list [options]
```

**参数**

| 参数 | 说明 |
| --- | --- |
| `--path <path>` | 指定项目路径（默认：当前目录） |
| `--page-size <number>` | 每页显示的版本数量（默认：10） |

**使用示例：**

```shell
# 查看版本列表：
shoplazza app versions list

# 指定每页显示的版本数量：
shoplazza app versions list --page-size 50

# 查看指定项目的版本：
shoplazza app versions list --path ./my-app
```

## 配置文件说明

### `shoplazza.app.toml` 应用配置文件

这是应用的核心配置文件，包含必要的应用信息：

```shell

# 应用 Client ID（必填）

client_id = "your-client-id"

# 应用权限范围

scopes = "read_customer write_cart_transform"
```

### `shoplazza.extension.toml` Extension 配置文件

每个 extension 都有自己的配置文件：

```shell
# Extension ID（由系统生成）

id = "extension-id"

# Extension 名称

name = "My Extension"

# Extension 类型（theme/checkout/function）

type = "theme"
```