> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 CLI 管理环境变量

> 用 squarecloud app env 列出、设置、移除或替换 Square Cloud 应用的环境变量，也可以从 .env 文件加载。

`squarecloud app env` 用于管理应用的环境变量。应用如何读取这些变量，请参阅[环境变量](/zh/platform/environment-variables)。

`list` 把应用 ID 作为参数。`set`、`remove` 和 `replace` 的参数用于变量，因此它们通过 `--app` 接收 ID。两者都是可选的：参见 [CLI 如何找到你的应用](/zh/cli-reference/quickstart#cli-如何找到你的应用)。

## `squarecloud app env list`

```bash 用法 theme={"system"}
squarecloud app env list [appID] [--json]
```

以 `KEY=value` 的形式打印每个变量，按名称排序。

```bash theme={"system"}
squarecloud app env list <appID> --json
# 以 JSON 对象打印变量。
```

## `squarecloud app env set`

```bash 用法 theme={"system"}
squarecloud app env set KEY=VALUE... [--from-file <path>] [--app <appID>]
```

| 标志 | 说明 |
| - | - |
| `--from-file <path>` | 从 `.env` 风格的文件中读取变量。`KEY=VALUE` 参数会覆盖文件中的同名键。 |
| `--app <appID>` | 要修改的应用。 |

设置一个或多个变量，其余变量保持不变。

```bash theme={"system"}
squarecloud app env set NODE_ENV=production PORT=80
# 在 ID= 行中的应用上设置两个变量。
```

```bash theme={"system"}
squarecloud app env set --from-file .env --app <appID>
# 设置 .env 文件中的所有变量。
```

```bash 输出 theme={"system"}
✓ Environment variables set: 2
```

## `squarecloud app env remove`

```bash 用法 theme={"system"}
squarecloud app env remove KEY... [--app <appID>]
squarecloud app env remove --all [--app <appID>] [-y]
```

**别名：** `delete`、`unset`

| 标志 | 说明 |
| - | - |
| `--all` | 确认后移除该应用的所有变量。不能与变量名同时使用。 |
| `-y`, `--yes` | 跳过 `--all` 的确认。 |
| `--app <appID>` | 要修改的应用。 |

```bash theme={"system"}
squarecloud app env remove API_KEY OLD_FLAG
# 移除两个变量。
```

## `squarecloud app env replace`

```bash 用法 theme={"system"}
squarecloud app env replace KEY=VALUE... [--from-file <path>] [--app <appID>] [-y]
```

| 标志 | 说明 |
| - | - |
| `--from-file <path>` | 从 `.env` 风格的文件中读取变量。 |
| `-y`, `--yes` | 跳过确认提示。 |
| `--app <appID>` | 要修改的应用。 |

用你传入的变量替换**整套**变量：未列出的变量会被移除。它会先要求 `y/N` 确认，并且至少需要一个变量。要移除所有变量，请使用 `remove --all`。

```bash theme={"system"}
squarecloud app env replace --from-file .env --app <appID> -y
# 不经询问，让应用的变量与 .env 中的完全一致。
```

## 包含空格和特殊字符的值

你的应用通过 shell 加载变量。为了让应用收到的每个值都与你输入的完全一致，CLI 会给包含空格或 `$`、`&`、`;`、`#` 等字符的值加上引号。之后 `env list` 显示的存储值会带有这些引号。

```bash theme={"system"}
squarecloud app env set 'GREETING=hello world'
# 应用读取到的值：hello world
```

用一对引号包裹的值会按原样发送，因此应用的 shell 可以展开它。可以用这种方式基于另一个变量构造值：

```bash theme={"system"}
squarecloud app env set 'API_URL="${HOST}:3000"'
# 应用读取到的是 HOST 的值后接 :3000。
```

## `--from-file` 的格式

* 每行一个 `KEY=VALUE`。空行、以 `#` 开头的行以及不含 `=` 的行会被跳过。
* 允许使用 `export ` 前缀，文件开头的 UTF-8 BOM 会被忽略。
* 包裹在成对引号中的值，取引号之间的原样内容。
* 在未加引号的值中，从 ` #` 开始的内容都是注释：`A=foo #bar` 设置的值为 `foo`。包含 ` #` 的值请加上引号。
* 不支持转义序列和跨多行的值。

## 相关内容

| 命令 | API | JavaScript SDK | VS Code |
| - | - | - | - |
| `list` | [`GET .../envs`](/zh/api-reference/endpoint/apps/envs/get) | [`api.apps.envs.get()`](/zh/sdks/js/environment_variables) | [环境变量](/zh/vscode-extension/features#应用) |
| `set` | [`POST .../envs`](/zh/api-reference/endpoint/apps/envs/add_n_edit) | [`api.apps.envs.set()`](/zh/sdks/js/environment_variables) | [环境变量](/zh/vscode-extension/features#应用) |
| `remove` | [`DELETE .../envs`](/zh/api-reference/endpoint/apps/envs/remove) | [`api.apps.envs.delete()`](/zh/sdks/js/environment_variables) | [环境变量](/zh/vscode-extension/features#应用) |
| `replace` | [`PUT .../envs`](/zh/api-reference/endpoint/apps/envs/overwrite) | [`api.apps.envs.replace()`](/zh/sdks/js/environment_variables) | |