# 主题开发

> Shoplazza CLI 的主题开发命令：基于 Nova 2023 创建脚手架，实时预览、拉取、推送、打包、分享预览链接，以及管理环境。

主题开发命令，用于创建脚手架、预览和发布主题。它们是 `shoplazza themes` 下不带 `+` 前缀的子命令，与[主题 API 命令](./themes-api)并列。

`pull`、`push`、`serve` 和 `share` 支持 `-e, --environment <名称>`，针对 `shoplazza.theme.toml` 中定义的环境执行，参见 [env](#env)。

## init

基于 Nova 2023 创建新主题脚手架。

```shell
shoplazza themes init --name <目录名>
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--name <目录名>` | string | 新主题的目标目录名（必填） |

无需登录。目标目录必须不存在或为空。

## serve

上传当前主题到店铺并启动实时预览。

```shell
shoplazza themes serve [参数]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--theme-id, -t <THEME_ID>` | string | 要预览并覆盖的主题 ID。如省略则使用当前目录的开发主题。 |
| `--environment, -e <名称>` | string | `shoplazza.theme.toml` 中的环境（店铺、profile、主题） |
| `--port <PORT>` | int | LiveReload 服务端口（默认：21647） |
| `--skip-push` | bool | 跳过启动时的全量上传，直接开始监听；只同步运行期间变更的文件 |
| `--task-id <TASK_ID>` | string | 继续等待之前的上传任务，不重新上传 |
| `--timeout <秒数>` | int | 监听指定秒数后退出（默认：0，一直监听直到中断） |

不传 `--theme-id` 时，首次运行会创建名为 `Development - <主题名>` 的开发主题，并把它的 ID 保存在 `.shoplazza/theme-state.json` 中（每个店铺一个），之后的运行会复用它。

返回内容：预览链接和主题编辑器链接。每次文件变更都会同步到主题并刷新已连接的浏览器。同步是单向的（本地到远端），主题编辑器中的修改需用 `themes pull` 拉取。命令会一直运行，直到按 Ctrl-C。

启动时的上传会用本地文件替换服务器上的主题文件：只存在于服务器上的文件会被删除，主题编辑器中的修改（包括 `config/settings_data.json`）会被覆盖。使用 `--skip-push` 可保留它们。

## pull

从 Shoplazza 店铺下载主题文件。

```shell
shoplazza themes pull [参数]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--theme-id, -t <THEME_ID>` | string | 要下载的主题 ID。除非 `-e` 已提供，否则必填；在终端中也可以从列表中选择 |
| `--environment, -e <名称>` | string | `shoplazza.theme.toml` 中的环境（店铺、profile、主题） |
| `--dry-run` | bool | 只打印将下载的内容和可能覆盖的本地文件，不发送请求 |

文件会解压到当前目录，随后店铺和主题会记录到 `shoplazza.theme.toml`（`default` 环境，或 `-e` 指定的环境）；文件不存在时会创建，修改已有环境前会先询问。

## push

上传本地主题文件到 Shoplazza 店铺，覆盖远端版本。

```shell
shoplazza themes push [参数]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--theme-id, -t <THEME_ID>` | string | 要覆盖的主题 ID。除非 `-e` 已提供，否则必填；在终端中也可以从列表中选择 |
| `--environment, -e <名称>` | string | `shoplazza.theme.toml` 中的环境（店铺、profile、主题） |
| `--task-id <TASK_ID>` | string | 继续等待之前的上传任务，不重新上传（超时错误中返回的 `task_id`） |
| `--dry-run` | bool | 只打印将上传的内容和目标，不打包也不发送请求 |

在终端中，`push` 覆盖主题前会请你确认。之后最多等待 10 分钟让服务器处理上传；等待超时后可用 `--task-id` 重新运行继续等待。与 `pull` 一样，它会把店铺和主题记录到 `shoplazza.theme.toml`。

## package

将本地主题文件打包为 ZIP 文件。

```shell
shoplazza themes package [参数]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--no-ignore` | bool | 忽略 .themeignore 规则（默认：false） |

## share

上传主题为新的未发布主题，并返回可分享的预览链接。不会覆盖已有主题。

```shell
shoplazza themes share [参数]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--environment, -e <名称>` | string | `shoplazza.theme.toml` 中的环境（店铺、profile） |
| `--dry-run` | bool | 只打印将作为新预览上传的内容，不打包也不发送请求 |

## env

查看和编辑 `shoplazza.theme.toml` 中的环境。CLI 会从当前目录向上查找该文件。

```shell
shoplazza themes env <命令> [名称] [参数]
```

| 命令 | 说明 |
|------|------|
| `themes env list` | 列出所有环境 |
| `themes env show [name]` | 查看单个环境（默认：`default`） |
| `themes env check [name]` | 离线校验每个环境都能对应到已登录的 profile；省略名称则检查全部 |
| `themes env add [name] --store <domain> [--theme <id>]` | 添加环境 |
| `themes env set [name] [--store <domain>] [--theme <id>]` | 修改已有环境，只改动传入的参数 |
| `themes env remove [name]` | 删除环境 |

```toml title="shoplazza.theme.toml"
[environments.default]
store = "my-store.myshoplaza.com"
theme = "123456"

[environments.staging]
store = "staging.myshoplaza.com"
theme = "654321"
```

用 `-e <名称>` 或环境变量 `SHOPLAZZA_CLI_ENVIRONMENT` 选择环境；两者都未设置时自动使用 `default` 环境。该文件不保存凭证，环境中的店铺需要有已登录的 profile。`add`、`set`、`remove` 改写文件时不保留注释。

## 相关

* [主题 CLI 指南](/zh-CN/docs/theme/developer-tools/shoplazza-cli/)
* [themes (API)](./themes-api) — 主题的完整 API 命令