> ## 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.

# Blob SDK：安装并创建客户端

> 安装 @squarecloud/blob，并使用 API 密钥或上传令牌创建 SquareCloudBlob 客户端。唯一的选项是 maxRetries。

<Info>
  本页记录的是 **`@squarecloud/blob` v4**。正从 v3 升级？请阅读 [v3 → v4 迁移指南](/zh/sdks/blob/migrating_to_v4)。
</Info>

`@squarecloud/blob` 是 [Square Cloud Blob Storage](/zh/services/blob) 的官方 JavaScript SDK。它覆盖了每一个 [Blob API](/zh/blob-reference/authentication) endpoint 以及 [S3 网关](/zh/blob-reference/s3-compatibility)。

## 要求

* **Node.js 20** 或更新版本，或任何现代浏览器。SDK 只使用 `fetch`、`FormData` 和 `Blob`。
* 同时提供 **ESM 和 CommonJS**，**没有任何运行时依赖**。
* `@aws-sdk/client-s3` 是一个**可选的对等依赖**，仅在调用 [`s3()`](/zh/sdks/blob/s3) 时需要。

## 安装

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @squarecloud/blob
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @squarecloud/blob
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @squarecloud/blob
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @squarecloud/blob
    ```
  </Tab>
</Tabs>

## 创建客户端

示例从环境变量 `SQUARECLOUD_API_KEY` 读取密钥。请在运行示例的终端中设置它：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={"system"}
    export SQUARECLOUD_API_KEY="your-api-key"
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={"system"}
    $env:SQUARECLOUD_API_KEY = "your-api-key"
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="ESM / TypeScript">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>

  <Tab title="CommonJS">
    ```javascript theme={"system"}
    const { SquareCloudBlob } = require("@squarecloud/blob");

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>
</Tabs>

用第一次调用检查客户端。`stats()` 会读取你的用量：

```typescript theme={"system"}
const { usage } = await blob.stats();

console.log(`${usage.objects} objects, ${usage.storage} bytes`);
```

它会打印对象数量及其占用的字节数，例如：

```text theme={"system"}
12 objects, 5242880 bytes
```

### 构造函数

```typescript theme={"system"}
new SquareCloudBlob(credential, { maxRetries: 2 });
```

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `credential` | `string` | 必填 | 一个 **API 密钥**，或一个只能调用 `put()` 的**上传令牌**（`squp_...`）。 |
| `options.maxRetries` | `number` | `2` | 可安全重复的请求（`GET` 或分片上传的某个分片）在网络错误或 `5xx` 之后重试的次数。`0` 表示禁用重试。参见[重试策略](/zh/sdks/blob/errors#重试策略)。 |

## 凭据

凭据会**原样**放入 `Authorization` 请求头发送，不带 `Bearer` 前缀。

| 凭据 | 来源 | 可执行的操作 |
| - | - | - |
| API 密钥 | [Square Cloud 控制台](https://squarecloud.app/zh/account/security) | 所有方法，受其 `blob:read` / `blob:write` [作用域](/zh/blob-reference/authentication#作用域)限制。 |
| 上传令牌（`squp_...`） | 在你的服务器上通过 [`blob.uploadTokens.create()`](/zh/sdks/blob/uploads#从浏览器上传) 生成 | 仅 `put()`。其他任何方法都会以 `403 UPLOAD_TOKEN_NOT_ALLOWED` 失败。 |

<Warning>
  切勿将 API 密钥发送到浏览器。请在你的服务器上生成上传令牌，并只将该令牌交给客户端。
</Warning>

## 无法配置的内容

`maxRetries` 是**唯一**的选项。客户端不接受：

* **基础 URL。** 它固定为 `https://blob.squarecloud.app/v1/`。
* **自定义 `fetch`。** 请求使用全局 `fetch`。
* **超时或 `AbortSignal`。** 调用会持续到 `fetch` 等待结束为止，且无法取消。
* **自定义请求头。**

## 方法

每个方法都返回纯数据（没有类），`s3()` 除外，它返回一个 `S3Client`。选项和结果使用 API 自身的字段名，大多为 snake\_case（`security_hash`、`expires_at`），因此 [Blob API 参考](/zh/blob-reference/authentication)可直接适用。

| 分组 | 方法 | 页面 |
| - | - | - |
| `blob` | `put(file, options)` | [上传](/zh/sdks/blob/uploads) |
| `blob.uploadTokens` | `create(options)` | [上传](/zh/sdks/blob/uploads#从浏览器上传) |
| `blob` | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [对象](/zh/sdks/blob/objects) |
| `blob.shares` | `create(object, options)`, `list()`, `revoke(id)` | [分享](/zh/sdks/blob/sharing) |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()` | [规则和统计](/zh/sdks/blob/rules_and_stats) |
| `blob` | `s3Credentials()`, `s3()` | [S3](/zh/sdks/blob/s3) |

该包还导出了 `SquareCloudBlobError`、`BlobErrorCode` 类型以及所有选项和结果类型（`PutOptions`、`PutResult`、`ListedObject`、`ObjectInfo`、`Share`、`Rule`……）。参见[错误](/zh/sdks/blob/errors)。

## 对象 ID

每个对象都由一个**不透明的 ID** 标识，例如公开对象为 `pub/...`，私有对象为 `prv/...`。

* **完全按返回的原样存储 ID。** 切勿手动构建 ID，也不要解析它。
* **更改 `private` 或 `expire` 会改变 ID。** 请始终用 [`update()`](/zh/sdks/blob/objects#更新对象) 返回的 ID 替换你存储的 ID。
* **使用响应中的 `url`**，而不是自行构建 URL。私有对象的 `url: null`：请通过 [`downloadUrl()`](/zh/sdks/blob/objects#下载链接) 或[分享](/zh/sdks/blob/sharing)获取链接。

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file
```

## 后续步骤

<CardGroup cols={3}>
  <Card title="上传" icon="upload" href="/zh/sdks/blob/uploads">
    上传文件并生成上传令牌。
  </Card>

  <Card title="Blob API 快速入门" icon="code" href="/zh/blob-reference/quickstart">
    基础 URL，以及用 curl 完成第一次上传。
  </Card>

  <Card title="Blob Storage 套餐" icon="box-archive" href="/zh/services/blob">
    每个套餐包含的内容。
  </Card>
</CardGroup>


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