一套代码，对接所有云存储：Files SDK 让文件上传下载不再为平台切换头疼

昆仑开源易选

2026-05-13 0 7

你是否曾为在不同项目中反复适配 AWS S3、Cloudflare R2、Vercel Blob、Google Cloud Storage 甚至本地文件系统而疲惫不堪？Files SDK 是一个轻量、现代的 TypeScript 文件存储 SDK，它用统一的 API 抽象了所有主流对象存储与 Blob 后端，让你写一次文件操作逻辑，就能无缝切换底层服务商——无需重写、无需条件判断、不绑定任何厂商。

核心功能

跨平台统一接口：无论后端是 S3、R2、GCS、Azure Blob、MinIO、Vercel Blob 还是本地磁盘，upload、download、list、delete、url、signedUploadUrl 等方法签名完全一致，参数和返回值结构高度标准化。
真· Web 标准 I/O：全程使用浏览器原生类型——Blob、File、ReadableStream、Uint8Array 或字符串，彻底告别各云厂商 SDK 自定义的 Buffer、Body、StreamWrapper 等“方言”，前后端类型更安全、调试更直观。
按需加载，零冗余：每个云适配器（如 files-sdk/s3、files-sdk/r2）都是独立入口点，Tree-shaking 友好。用哪个就 import 哪个，打包体积不因支持多平台而膨胀。
保留原厂能力的「逃生舱口」：通过 files.raw 可随时访问底层 SDK 的原始客户端（如 AWS SDK v3 的 S3Client 或 Cloudflare Workers 的 R2Bucket），需要高级特性（如 multipart upload、server-side encryption 配置）时一步直达，不牺牲灵活性。
面向边缘与 Serverless 优化：专为 Vercel、Cloudflare Workers、Deno Deploy 等无服务器环境设计，适配其运行时限制（如无 Node.js fs 模块），同时兼容浏览器、Node.js 和 Deno，真正全栈可用。
开箱即用的消费者平台支持：不仅覆盖基础设施级存储（S3/R2/GCS），还计划/已支持 Dropbox、Notion 等消费级文件服务，未来可统一管理企业云存与用户授权文件源。

适合哪些人用

如果你是以下角色之一，Files SDK 极可能成为你新项目的默认依赖：
• 全栈或前端开发者，正构建需要上传头像、文档、媒体文件的应用，且希望未来能灵活更换云服务商；
• SaaS 或 CMS 工具作者，需为客户提供「自选存储后端」能力（比如让用户填自己的 S3 密钥或接入自家 MinIO）；
• 边缘计算实践者，在 Cloudflare Workers 或 Vercel Edge Functions 中处理文件，厌倦了为每个平台写重复胶水代码；
• 开源库维护者，想提供「存储无关」的文件操作抽象层，降低下游用户的集成门槛。

快速上手

只需两步，5 分钟接入任意存储：

1. 安装依赖：

npm install files-sdk

2. 编写通用逻辑（以 Cloudflare R2 为例）：

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


const files = new Files({
  adapter: r2({ bucket: env.MY_R2_BUCKET }),
});

// 所有操作都一样！ await files.upload("reports/q3.pdf", pdfBlob, { contentType: "application/pdf" }); const data = await files.download("reports/q3.pdf"); // 返回 Blob const url = await files.url("reports/q3.pdf"); // 直接生成可公开访问的 URL

想切到 AWS S3？只需把 import { r2 } from "files-sdk/r2" 换成 import { s3 } from "files-sdk/s3"，其余代码一行不用改。