> ## 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 Storage 中的公开 URL、临时链接和分享链接：各自的适用场景、有效期，以及文件可见性变化时会发生什么。

Blob Storage 提供三种把文件交给他人的方式。根据链接需要存活多久以及是否需要收回来选择。

|        | 公开 URL                                         | 临时链接                                         | 分享链接                                              |
| ------ | ---------------------------------------------- | -------------------------------------------- | ------------------------------------------------- |
| 创建方式   | [对象上传](/zh/blob-reference/endpoint/post)（公开文件） | [对象下载](/zh/blob-reference/endpoint/download) | [创建分享](/zh/blob-reference/endpoint/shares-create) |
| 地址     | `blob.squarecloud.dev/pub/...`                 | `files.squarecloud.dev/d/...`                | `files.squarecloud.dev/s/...`                     |
| 适用于    | 公开文件                                           | 公开与私有文件                                      | 公开与私有文件                                           |
| 有效期    | 文件保持公开期间                                       | 60 秒到 24 小时                                  | 60 秒到 30 天                                        |
| 能否撤销   | 将文件设为私有                                        | 否                                            | 是                                                 |
| 下载次数上限 | 否                                              | 否                                            | 可选，1 到 10000                                      |
| 密码     | 否                                              | 否                                            | 可选（Pro 和 Enterprise）                              |
| 分发来源   | 全球 CDN                                         | Blob Storage                                 | Blob Storage                                      |

## 公开 URL

公开文件在 CDN 上拥有永久 URL：

```
https://blob.squarecloud.dev/pub/<user_id>/<path>
```

将它用于需要嵌入的资源：网站上的图片、机器人中的附件、其他服务要获取的文件。2026 年 9 月更新之前存储的旧版文件保留其位于 `https://public-blob.squarecloud.dev/<user_id>/<path>` 的 URL 30 天，直至 2026 年 10 月 25 日。使用 [Object Copy](/zh/blob-reference/endpoint/copy)（`move: true`）移动文件，即可获得 `blob.squarecloud.dev` 上的 URL。

<Tip>当 `security_hash=true`（私有文件和未指定名称的上传令牌的默认值）时，路径会带上一个随机后缀，因此无法根据名称猜出 URL。</Tip>

## 临时链接

[对象下载](/zh/blob-reference/endpoint/download)会为单个文件签发一个链接，有效期为 60 秒到 24 小时（默认 1 小时）。用它来立即交付私有文件：下载按钮、电子邮件附件、由你的后端传给其他服务的文件。

* 该链接无需任何凭证，且**无法撤销**：只有在过期，或文件被删除、移动或可见性改变时才会失效。请将有效期设得短一些。
* 它支持 `Range`（断点续传和视频拖动）以及条件请求（`If-None-Match`、`If-Modified-Since`）。
* 你可以强制下载，并指定浏览器保存的文件名（`disposition` 和 `filename`）。
* 对于未设置这些覆盖项的公开文件，对象下载会直接返回公开 URL 本身。
* 每个链接对每个 IP 每分钟接受 60 次请求，此外你账户的所有链接还共享一个总体限制。超出后以纯文本返回 `429`。要把一个文件交给很多人，请将其设为公开：公开文件由 CDN 分发，不受此限制。已过期或无效的链接返回 `404`。

## 分享链接

[创建分享](/zh/blob-reference/endpoint/shares-create)会生成一个带有独立页面的链接，面向人而不是程序：把文件发给客户、把报告发给团队、把构建版本发给测试人员。

* 有效期为 60 秒到 30 天（默认 24 小时）。
* 可以随时通过[删除分享](/zh/blob-reference/endpoint/shares-delete)**撤销**，并可通过[分享列表](/zh/blob-reference/endpoint/shares-list)列出。
* `max_downloads` 限制文件可被下载的次数。即使在并发下载时，计数也是精确的。次数用尽后，该链接返回 `410`。
* 在 **Pro 和 Enterprise** 计划上，设置 `password` 后页面会在下载前要求输入密码。错误尝试按 IP 和按链接进行限制。降级之前创建的带密码链接会保留其密码。
* 页面语言跟随访问者的浏览器语言（英语、葡萄牙语、西班牙语、法语、德语、意大利语、日语和中文）。
* 账户最多可拥有 1000 个有效的分享链接。
* 下载私有文件会经过一个临时链接，限制相同：每个 IP 每分钟 60 次请求，外加你账户的总体限制。

分享链接绑定的是创建链接时的文件状态。删除文件、移动或重命名文件，或更改其可见性，都会使该链接立即返回 `404`，这发生在任何密码页面之前，也不会消耗下载次数。下一次访问会将其从[分享列表](/zh/blob-reference/endpoint/shares-list)中移除。

<Warning>
  指向**公开**文件的分享链接最终会重定向到该文件的永久公开 URL。打开链接的人会拿到这个 URL，之后无需经过链接就能再次下载文件，因此密码、下载次数上限和有效期只能真正保护**私有**文件。如果保护很重要，请分享私有文件。
</Warning>

## 将文件设为私有或公开

通过[对象更新](/zh/blob-reference/endpoint/update)（`private: true` 或 `false`）更改可见性，或在使用[对象复制](/zh/blob-reference/endpoint/copy)复制时更改。

* 对象 **id 会改变**：`pub/...` 变为 `prv/...`，反之亦然。请保存响应中的新 `id`。
* **将文件设为私有**会在请求返回之前删除公开副本。其公开 URL 随即失效，CDN 缓存会在约 60 秒内将其清除。如果公开副本无法删除，该对象会返回 `VISIBILITY_CHANGE_FAILED` 并**保持公开**，以便你重试。
* **将文件设为公开**需要付费计划。设为私有则始终允许，即使没有计划也可以。
* 指向该文件的分享链接和临时链接会失效，因为它们指向的是旧 id。请为新 id 创建新的链接。

<Warning>曾经公开的文件，在你将其设为私有之前可能已被他人下载或缓存。敏感文件请从一开始就以私有方式上传（`private=true`）。</Warning>