> ## 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 管理 Blob Storage 文件

> 用 squarecloud blob 列出、上传、删除 Square Cloud Blob Storage 中的文件并获取其链接，还可以查看你用了多少套餐存储空间。

`squarecloud blob` 用于管理你的 [Blob Storage](https://docs.squarecloud.app/zh/services/blob.md) 中的文件。文件通过其 ID 来标识，`blob list` 和 `blob upload` 会打印该 ID。

这些命令需要具有 `blob:read` 和 `blob:write` [scope](https://docs.squarecloud.app/zh/blob-reference/authentication.md#作用域) 的 API 密钥。浏览器登录会同时申请这两个 scope。3.2.0 版本之前通过浏览器登录获得的密钥缺少它们：此时第一个 Blob 命令会请你再次运行 `squarecloud auth login`。`SQUARECLOUD_API_KEY` 中的密钥同样需要这两个 scope。

## `squarecloud blob list`

```bash 用法 theme={"system"}
squarecloud blob list [prefix] [--json]
```

打印每个文件的 ID、大小、创建日期和 URL，或只打印 `prefix` 下的文件。私有文件会显示 `(private)`，而不是 URL。

```bash theme={"system"}
squarecloud blob list avatars/
# 只列出 avatars/ 下的文件。
```

使用 `--json` 时，它会以 JSON 数组的形式打印这些文件。

## `squarecloud blob upload`

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

| 标志 | 说明 |
| - | - |
| `--name <name>` | 以这个名称（不含扩展名）保存文件。默认名称是去掉扩展名后的文件名。 |
| `--private` | 将文件保存为私有：它没有公开 URL，只能通过临时链接访问。 |

上传一个文件，并打印它的 ID 和 URL。服务会保留文件的扩展名。在默认名称中，服务不接受的字符会被替换为 `_`。要发送文件夹，请先用 [`squarecloud zip`](https://docs.squarecloud.app/zh/cli-reference/deploy#squarecloud-zip) 把它压缩。

```bash theme={"system"}
squarecloud blob upload ./video.mp4
```

```bash 输出 theme={"system"}
Uploading video.mp4 (1.20 GB)...
Sent part 77 of 77
✓ Uploaded as <ID>
  <URL>
```

* **大文件：** 超过 90 MiB 的文件会分片上传，每次 6 个分片，分片大小根据服务返回的限制确定。进度输出到 stderr，因此 stdout 只包含结果。
* **失败：** 失败或被取消（`Ctrl+C`）的上传会被中止，因此不会占用你的未完成上传名额。只有读取和分片会被重试，速率限制永远不会重试。
* **私有文件：** CLI 不会显示 URL，而是显示生成临时链接的命令 [`blob url`](#squarecloud-blob-url)。

使用 `--json` 时，stdout 只以 JSON 格式输出已保存的文件（ID、可见性、URL 和大小，分片上传时还包括分片数量）。

## `squarecloud blob url`

```bash 用法 theme={"system"}
squarecloud blob url <id> [--json]
```

打印文件的下载链接：公开文件的公开 URL，或私有文件的临时链接。只有链接会输出到 stdout，因此它可以用在 `$(...)` 中。对于临时链接，CLI 会在 stderr 上说明它的有效期限。

```bash theme={"system"}
curl -o report.pdf "$(squarecloud blob url <ID>)"
# 下载一个文件，公开或私有均可。
```

使用 `--json` 时，它会打印链接及其过期时间、可见性、大小和内容类型。

## `squarecloud blob delete`

```bash 用法 theme={"system"}
squarecloud blob delete <id> [-y]
```

| 标志 | 说明 |
| - | - |
| `-y`, `--yes` | 跳过确认提示。 |

> [!WARNING]
>
> 删除文件是永久性的：没有回收站。

删除前会询问 `Delete <ID> for good? There is no trash [y/N]`。`delete` 没有 JSON 输出。

## `squarecloud blob stats`

```bash 用法 theme={"system"}
squarecloud blob stats [--json]
```

显示你存储了多少个文件，以及它们占用了多少套餐存储空间。

```bash 输出 theme={"system"}
Files: <count>
Storage: <used> used of the <included> in your plan
```

使用 `--json` 时，它会以 JSON 格式打印完整的用量记录。

## 相关内容

| 命令 | API | Blob SDK |
| - | - | - |
| `list` | [`GET /v1/objects`](https://docs.squarecloud.app/zh/blob-reference/endpoint/list) | [`blob.list()`](https://docs.squarecloud.app/zh/sdks/blob/objects#列出对象) |
| `upload` | [`POST /v1/objects`](https://docs.squarecloud.app/zh/blob-reference/endpoint/post)、[分块上传](https://docs.squarecloud.app/zh/blob-reference/endpoint/chunked-init.md) | [`blob.put()`](https://docs.squarecloud.app/zh/sdks/blob/uploads) |
| `url` | [`GET /v1/objects/download`](https://docs.squarecloud.app/zh/blob-reference/endpoint/download) | [`blob.downloadUrl()`](https://docs.squarecloud.app/zh/sdks/blob/objects#下载链接) |
| `delete` | [`DELETE /v1/objects`](https://docs.squarecloud.app/zh/blob-reference/endpoint/delete) | [`blob.delete()`](https://docs.squarecloud.app/zh/sdks/blob/objects#删除) |
| `stats` | [`GET /v1/account/stats`](https://docs.squarecloud.app/zh/blob-reference/endpoint/stats) | [`blob.stats()`](https://docs.squarecloud.app/zh/sdks/blob/rules_and_stats#统计) |

要在你自己的代码中使用 Blob Storage，请从 [Blob SDK](https://docs.squarecloud.app/zh/sdks/blob/client.md) 开始。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.