> ## 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.shares 创建、列出和撤销分享链接，并在分享与 downloadUrl() 链接之间做出选择。

**分享**是指向单个对象的链接，它可以**过期**、可以被**撤销**、可以限制**下载次数**，在 Pro 和 Enterprise 套餐上还可以要求**密码**。链接的行为方式请参见[链接与分享](/zh/blob-reference/links-and-sharing)。

## 分享还是 `downloadUrl()`？

|        | [`downloadUrl()`](/zh/sdks/blob/objects#下载链接) | `shares.create()`      |
| ------ | --------------------------------------------- | ---------------------- |
| 公开对象   | 永久 CDN URL（`expires_at: null`）                | 重定向到永久公开 URL（参见下方警告）   |
| 私有对象   | 临时链接，最长 24 小时                                 | 分享链接，最长 30 天           |
| 可撤销    | **否**                                         | 是，使用 `shares.revoke()` |
| 下载次数限制 | 否                                             | 是，`max_downloads`      |
| 密码     | 否                                             | 是，Pro 和 Enterprise     |

对于由你自己分发的短期链接，请使用 `downloadUrl()`；当你需要收回链接或控制谁可以下载时，请使用分享。

## 创建分享

```typescript theme={"system"}
const share = await blob.shares.create(id, {
    expires_in: 86400,     // seconds, 60 to 2592000 (default 86400)
    max_downloads: 10,     // 1 to 10000
    password: "secret123", // 8 to 128 characters, Pro and Enterprise
});

console.log(share.url);
```

| 选项              | 类型       | 说明                                                       |
| --------------- | -------- | -------------------------------------------------------- |
| `expires_in`    | `number` | 链接有效期（秒），60 到 2592000（30 天）。默认 86400。                    |
| `max_downloads` | `number` | 1 到 10000。                                               |
| `password`      | `string` | 8 到 128 个字符。Pro 和 Enterprise；其他套餐会收到 `UPGRADE_REQUIRED`。 |

结果包含 `id`、`url`、`expires_at`、`max_downloads`、`password`（是否设置了密码）、`object` 和 `object_is_public`。

<Warning>
  如果 `object_is_public` 为 `true`，分享链接会重定向到对象的**永久公开 URL**：密码、下载次数限制和过期时间**起不到任何保护作用**，因为该文件仍可通过那个 URL 访问。请先将对象设为私有，然后再分享：

  ```typescript theme={"system"}
  const [result] = await blob.update(id, { private: true });
  if (result.ok) {
      id = result.id; // the id changes
      const share = await blob.shares.create(id, { max_downloads: 1 });
  }
  ```
</Warning>

## 列出分享

```typescript theme={"system"}
const shares = await blob.shares.list();
```

返回一个分享数组，每个分享都包含 `id`、`url`、`object`、`expires_at`、`remaining_downloads`、`password` 和 `created_at`。

## 撤销分享

```typescript theme={"system"}
await blob.shares.revoke(share.id);
```

该链接将停止工作。`revoke()` 不返回任何内容，撤销不存在的分享会以 `SHARE_NOT_FOUND` 失败。

<Tip>
  删除、移动或重命名对象，或更改其可见性，也会使其分享链接失效：它们指向的是旧 ID。请为新 ID 创建新的分享。
</Tip>

<Note>
  `shares.create()` 和 `shares.revoke()` 只有**一次尝试**。只有读操作 `shares.list()` 会被[重试](/zh/sdks/blob/errors#重试策略)。
</Note>

API 参考：[Create Share](/zh/blob-reference/endpoint/shares-create)、[List Shares](/zh/blob-reference/endpoint/shares-list)、[Delete Share](/zh/blob-reference/endpoint/shares-delete)。