> ## 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 upload 把文件夹部署为新的 Square Cloud 应用，用 squarecloud commit 发送改动，并用 squarecloud zip 检查 zip 的内容。

* **`upload`** 创建一个**新**应用，并分配新的 ID。
* **`commit`** 把文件发送到一个**已存在**的应用，并保留它的 ID、域名和设置。
* **`zip`** 在本地生成同样的 zip 但不发送，方便你检查其中包含哪些内容。

`upload` 和 `commit` 也可以在 `squarecloud app` 下使用（`squarecloud app upload`、`squarecloud app commit`）。第一次使用？请从[快速开始](/zh/cli-reference/quickstart)入手。

## zip 中包含哪些内容

`upload`、`commit` 和 `zip` 会压缩当前文件夹，并排除项目根目录下 [`squarecloud.ignore`](/zh/getting-started/squarecloud-ignore) 中列出的内容。该文件使用 `.gitignore` 语法，[VS Code 扩展](/zh/vscode-extension/features#忽略规则)读取的也是同一个文件。

* **始终最先排除：** `node_modules`、`.git`、`.github`、`.vscode`、`package-lock.json`、`pnpm-lock.yaml` 和 `yarn.lock`。依赖会在平台上根据你的清单文件安装。如果你需要固定版本而要发送锁文件，请添加一条 `!` 规则，例如 `!package-lock.json`。
* **链接：** 指向文件的符号链接会作为该文件打包；指向文件夹的链接和失效的链接会被跳过，并在 stderr 上给出说明。
* **旧的文件名**（`.squareignore`、`.squarecloudignore`、`square.ignore`）在缺少 `squarecloud.ignore` 时仍会被读取，同时会提示你重命名该文件。

## `squarecloud upload`

```bash 用法 theme={"system"}
squarecloud upload [--file <path>] [--json]
```

压缩当前文件夹，并用它创建一个新应用。该文件夹中需要有 [`squarecloud.app` 或 `squarecloud.config`](/zh/getting-started/config-file) 文件。

| 标志 | 说明 |
| - | - |
| `--file <path>` | 上传你已有的 zip，而不是压缩当前文件夹。相对路径和绝对路径都可以。 |

```bash theme={"system"}
squarecloud upload
# 压缩当前文件夹，并将其部署为新应用。
```

```bash theme={"system"}
squarecloud upload --file ./build/my-app.zip
# 上传一个已有的 zip。
```

```bash 输出 theme={"system"}
Compressing the current directory.
Uploading the zip file to Square Cloud.

✓ Application uploaded to Square Cloud!
  Open it at https://squarecloud.app/dashboard/applications/<appID>
```

上传成功后，CLI 会把 `ID=<appID>` 写入当前文件夹的配置文件，让后续命令知道你指的是哪个应用。参见[应用 ID 保存在哪里](/zh/cli-reference/quickstart#应用-id-保存在哪里)。

使用 `--json` 时，stdout 只输出所创建应用的 JSON（ID、名称、描述、域名、集群、内存、CPU 和语言）；进度消息输出到 stderr。

## `squarecloud commit`

```bash 用法 theme={"system"}
squarecloud commit [appID] [--file <path>] [--path <dir>] [-r]
```

**别名：** `squarecloud push`、`squarecloud app commit`、`squarecloud app push`

压缩当前文件夹并发送到一个已有的应用。ID 来自参数，或来自配置文件中的 `ID=` 行。与其他命令不同，`commit` 从不打开选择器：两者都没有时，它会以退出码 1 停止。

| 标志 | 说明 |
| - | - |
| `--file <path>` | 发送单个文件，而不是当前文件夹。zip 会在应用中解压；其他文件则以原有名称写入。相对路径和绝对路径都可以。 |
| `--path <dir>` | commit 到应用的这个文件夹，而不是根目录。 |
| `-r`, `--restart` | commit 完成后重启应用。 |

```bash theme={"system"}
squarecloud commit
# 把当前文件夹发送到 ID= 行中的应用。
```

```bash theme={"system"}
squarecloud commit <appID> --restart
# 把当前文件夹发送到指定应用，然后重启它。
```

```bash theme={"system"}
squarecloud commit --file ./config.json --path settings
# 把一个文件发送到应用的 settings 文件夹。
```

```bash 输出 theme={"system"}
Compressing the current directory.
Committing to your application (<appID>)...
Committed to your application.
```

大型 commit 不会因超时而被中断。`commit` 没有 JSON 输出。

## `squarecloud zip`

```bash 用法 theme={"system"}
squarecloud zip
```

以与 `upload` 和 `commit` 相同的方式压缩当前文件夹，并在该文件夹内保存为 `<folder name>.zip`，同名的现有文件会被替换。此命令不需要登录。

```bash 输出 theme={"system"}
✓ Your project was zipped to <folder name>
```

如果无法写入 zip，CLI 会打印 `Couldn't zip your application.` 及原因；如果无法删除旧的 `<folder name>.zip`，它也会说明。这两种情况都会以退出码 1 退出。

## 相关内容

| 命令 | API | JavaScript SDK | VS Code |
| - | - | - | - |
| `upload` | [`POST /v2/apps`](/zh/api-reference/endpoint/apps/upload) | [`api.apps.create()`](/zh/sdks/js/commit_and_upload) | [上传新应用](/zh/vscode-extension/features#上传新应用) |
| `commit` | [`POST /v2/apps/{app_id}/commit`](/zh/api-reference/endpoint/apps/commit) | [`api.apps.commit()`](/zh/sdks/js/commit_and_upload) | [Commit](/zh/vscode-extension/features#将更改-commit-到现有应用) |

如果想在每次推送时自动部署，请参阅 [GitHub 部署](/zh/cli-reference/github-deploys)。