Files SDK

Files SDK：跨平台的统一对象与 Blob 存储开发利器

在现代 Web 开发中，处理对象存储（Object Storage）和 Blob 后端往往是一项繁琐的任务。不同的供应商（如 AWS S3、Cloudflare R2、Vercel Blob 等）拥有各自微妙差异的 SDK。Files SDK 应运而生，它由开发者 Hayden Bleasel 打造，旨在提供一个“统一的存储 SDK”，通过一个简洁、诚实的 API 来管理所有的对象存储需求。

什么是 Files SDK？

Files SDK 是一个轻量级且高效的统一存储 SDK，专为对象和 Blob 后端设计。它的核心理念是将复杂的供应商差异抽象化，暴露出一组在所有平台通用的核心操作接口，如上传（upload）、下载（download）、列表（list）和删除（delete）。

Files SDK 不仅仅是一个抽象层，它还拥抱 Web 标准 I/O，并提供了一个“逃生舱”（Escape hatch）功能，确保在需要使用供应商特定功能时，开发者可以随时调用原生客户端。这使得 Files SDK 成为了一款既保持通用性又不失灵活性的开发工具。

Files SDK 的核心特性

1. 跨供应商的统一 API

Files SDK 在不同的存储提供商之间暴露了相同的一小部分 API 接口。这意味着您可以轻松更换存储提供商，而无需重写大量的业务代码。无论是从 AWS S3 迁移到 Cloudflare R2，还是从 Vercel Blob 切换到本地 MinIO，Files SDK 都能保证调用方式的一致性。

2. 基于 Web 标准的 I/O

Files SDK 深度集成 Web 标准，能够接受 File、Blob、ReadableStream、ArrayBuffer 以及简单的字符串输入。这使得它可以在任何运行 fetch 的环境（如 Node.js、Bun、Cloudflare Workers、Vercel 等）中无缝运行。

3. 原生客户端逃生舱 (Escape Hatch)

如果您需要处理版本控制、生命周期管理、ACL 或分段上传等特定功能，Files SDK 提供的 files.raw 属性就是您的“逃生舱”。它允许您直接访问底层经过类型定义的供应商原生客户端，从而不限制开发者使用任何高级功能。

4. 可预测的错误处理

在处理多种存储后端时，错误码的差异通常令人头疼。Files SDK 通过 FilesError 类标准化了错误处理，在所有供应商中提供统一的错误代码，同时将原始错误作为 cause 附加其后，极大地方便了调试工作。

5. 按需安装的对等依赖

为了保持项目的轻量，Files SDK 将每个供应商的原生 SDK 设为可选的对等依赖（peer dependency）。您只需安装 files-sdk 以及您实际使用的那一个供应商 SDK，避免了不必要的包体积冗余。

如何安装 Files SDK

您可以根据自己习惯使用的包管理工具进行安装：

• 使用 npm:

  npm install files-sdk
  

• 使用 pnpm:

  pnpm add files-sdk
  

• 使用 bun:

  bun add files-sdk
  

• 使用 yarn:

  yarn add files-sdk
  

注意： 请务必安装您所选适配器对应的原生 SDK。如果您在没有安装对等依赖的情况下导入适配器，Node.js 会抛出 ERR_MODULE_NOT_FOUND 错误。

如何使用 Files SDK (快速入门)

使用 Files SDK 非常直观。首先使用特定供应商的适配器构造一个 Files 实例，然后即可调用相应方法。

基础代码示例：

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

// 初始化 Files 实例
const files = new Files({
  adapter: s3({ bucket: "uploads", region: "us-east-1" }),
});

// 执行存储操作
await files.upload("hello.txt", "world"); // 上传文件
const file = await files.download("hello.txt"); // 下载文件
const { items } = await files.list({ prefix: "hello" }); // 列出文件
await files.delete("hello.txt"); // 删除文件

适配器在构造时即已固定，这种设计保持了调用点的平整性，避免了在每次调用时都需要传入提供商参数的复杂感。

广泛的兼容性矩阵

Files SDK 支持几乎所有主流的对象存储服务，每种适配器都实现了相同的十个核心方法。以下是 Files SDK 支持的部分提供商列表：

• 公有云巨头: AWS S3, Google Cloud Storage (GCS), Azure, IBM COS, Alibaba OSS, Tencent COS.
• 边缘计算与 Blob 存储: Cloudflare R2, Vercel Blob, Netlify Blobs.
• 自托管与兼容 S3 服务: MinIO, DigitalOcean, Bun S3, Wasabi, Backblaze B2, Ceph (通过 S3).
• 第三方存储与网盘: Dropbox, Google Drive, OneDrive, SharePoint, Box, Supabase, Cloudinary.
• 本地与开发者工具: Filesystem (本地文件系统), Appwrite, Firebase Storage.

典型使用场景 (Use Case)

1. 跨云存储管理

当您的应用需要同时使用多个云厂商的存储服务，或者需要从一个平台迁移到另一个平台时，Files SDK 可以显著降低切换成本。只需更改适配器配置，核心逻辑完全不动。

2. 边缘函数 (Edge Functions)

由于 Files SDK 运行在任何支持 fetch 的环境中，它是 Cloudflare Workers 或 Vercel Edge Functions 的理想选择。它支持 ReadableStream 和 Blob，非常适合处理流式上传和下载。

3. 企业级应用开发

通过标准化的错误码和类型安全的 files.raw 逃生舱，大型团队可以编写更健壮的代码，同时保留对底层存储引擎的高级控制权。

常见问题 (FAQ)

Q: Files SDK 会增加我的项目体积吗？ A: 不会。Files SDK 本身非常轻量。它采用了对等依赖机制，您只需要安装您实际使用的存储供应商 SDK，不需要的供应商驱动不会被包含在您的项目中。

Q: 如果我需要 S3 的特定功能（如设置 ACL），Files SDK 能做到吗？ A: 可以。虽然 Files SDK 的核心 API 保持通用，但您可以通过 files.raw 直接访问底层的原生客户端（例如 AWS SDK 实例），从而调用任何特定于供应商的功能。

Q: Files SDK 支持哪些运行环境？ A: Files SDK 具有极佳的兼容性，可运行在 Node.js、Bun、Web Workers、Cloudflare Workers、Vercel 边缘环境以及任何现代 Web 浏览器中。

Q: 错误处理是如何工作的？ A: 当操作失败时，Files SDK 会抛出一个 FilesError。这个错误带有一个规范化的代码（code），在所有供应商之间是一致的。原始错误则存储在 cause 属性中，方便进一步排查。