S3已成为文件存储标准，阿里/腾讯/华为云都支持，Bun率先原生支持

就这几行：

import{S3Client}from"bun"// 阿里 const aliyun=new S3Client({accessKeyId: process.env.ALI_KEY!, secretAccessKey: process.env.ALI_SECRET!, bucket:"my-bucket", endpoint:"https://oss-cn-hangzhou.aliyuncs.com",})await aliyun.write("hello.txt","兄弟们好啊")// 腾讯 const tx=new S3Client({accessKeyId: process.env.TX_KEY!, secretAccessKey: process.env.TX_SECRET!, bucket:"my-bucket-1250000000", endpoint:"https://cos.ap-guangzhou.myqcloud.com",})await tx.write("hello.txt","兄弟们好啊")// 华为 const hw=new S3Client({accessKeyId: process.env.HW_KEY!, secretAccessKey: process.env.HW_SECRET!, bucket:"my-bucket", endpoint:"https://obs.cn-north-4.myhuaweicloud.com",})await hw.write("hello.txt","兄弟们好啊")

同一份 Bun.S3 API，阿里、腾讯、华为三家云全通。

bun run demo.ts

完事儿。

痛点：每家云一套 SDK

兄弟们，搞过后端上传下载的都知道。

文件存储这事儿，国内国外云厂商各写一套 SDK：

• • 阿里：OSS，用ali-oss

• • 腾讯：COS，用cos-nodejs-sdk-v5

• • 华为：OBS，用esdk-obs-nodejs

• • AWS：S3，用aws-sdk

**想换一家？**代码全部推倒重写。

更糟的是这堆 SDK：

• • 包大，冷启动 80MB 往上

• • 文档各看各的，调半天

• • 流式上传、分片上传、签名算法各搞一套

**老板让你上华为云，**你对着阿里 SDK 写好的代码干瞪眼。

解决方案：S3 是行业事实标准

S3 是 AWS 在2006 年搞出来的对象存储。

S3 协议太成功了，现在已经是行业事实标准。

啥叫事实标准？

• •AWS S3自己当然支持

• •阿里云 OSS100% 兼容 S3

• •腾讯云 COS100% 兼容 S3

• •华为云 OBS100% 兼容 S3

• • Cloudflare R2、MinIO、七牛、京东云、金山云全部兼容

一套 API 写完，换云只改 endpoint。

而 Bun，率先把 S3 客户端焊死在运行时里。

Bun.S3Client一个类，吃遍所有 S3 兼容服务。

**这是 Bun 1.2 才有的真本事，**Node.js 至今没原生 S3，要装aws-sdk一大坨。

一句话：啥是 S3 协议？

S3 协议就是一套 HTTP REST API：

• •PUT /<bucket>/<key>：上传文件

• •GET /<bucket>/<key>：下载文件

• •DELETE /<bucket>/<key>：删除文件

• •LIST /<bucket>：列文件

每家云厂商对外暴露这四个动词，加上AWS 签名 v4鉴权。

**只要你的代码按 S3 协议发请求，**哪家云都能接住。

阿里 OSS：endpoint 是关键

阿里云 OSS 的 S3 兼容端点长这样：

import{S3Client}from"bun"const oss=new S3Client({accessKeyId:"LTAIxxxxxxxx", secretAccessKey:"xxxxxxxx", bucket:"my-bucket", region:"oss-cn-hangzhou", endpoint:"https://oss-cn-hangzhou.aliyuncs.com",})await oss.write("hello.txt","兄弟们好啊")const txt=await oss.file("hello.txt").text()console.log(txt)

**坑点：bucket 名要全球唯一。**阿里控制台开完桶，把名字填到bucket字段。

region用oss-cn-hangzhou这种格式，跟 AWS 的us-east-1不一样，别照搬。

腾讯 COS：bucket 名带 APPID

腾讯 COS 有点特殊。

bucket 名必须带 APPID 后缀：

import{S3Client}from"bun"const cos=new S3Client({accessKeyId:"AKIDxxxxxxxx", secretAccessKey:"xxxxxxxx", bucket:"my-bucket-1250000000", // ← 注意 APPID region:"ap-guangzhou", endpoint:"https://cos.ap-guangzhou.myqcloud.com",})await cos.write("hello.txt","兄弟们好啊")

1250000000这种数字就是你腾讯云账号的 APPID。

**没加 APPID？**404 报错，找不到桶。

控制台创建桶的时候会带，复制粘贴即可。

华为云 OBS：endpoint 长得很像

华为云 OBS 跟 AWS S3 几乎一模一样。

连region字段格式都照搬：

import{S3Client}from"bun"const obs=new S3Client({accessKeyId:"HECxxxxxxxx", secretAccessKey:"xxxxxxxx", bucket:"my-bucket", region:"cn-north-4", endpoint:"https://obs.cn-north-4.myhuaweicloud.com",})await obs.write("hello.txt","兄弟们好啊")

华为云的region格式跟 AWS 一致：

• •cn-north-4北京

• •cn-east-3上海

• •cn-south-1广州

从 AWS 迁到华为云，改个 endpoint 就行。

一份代码通吃三家：工厂模式

兄弟们，写过电商/OA/CRM 的都知道。

多云适配是硬需求。

把三家云封装成工厂：

import{S3Client}from"bun"typeVendor="aliyun"|"tencent"|"huawei"const config: Record<Vendor, any>={aliyun:{bucket: process.env.ALI_BUCKET!, region:"oss-cn-hangzhou", endpoint:"https://oss-cn-hangzhou.aliyuncs.com", accessKeyId: process.env.ALI_KEY!, secretAccessKey: process.env.ALI_SECRET!,}, tencent:{bucket: process.env.TX_BUCKET!, // 带 APPID region:"ap-guangzhou", endpoint:"https://cos.ap-guangzhou.myqcloud.com", accessKeyId: process.env.TX_KEY!, secretAccessKey: process.env.TX_SECRET!,}, huawei:{bucket: process.env.HW_BUCKET!, region:"cn-north-4", endpoint:"https://obs.cn-north-4.myhuaweicloud.com", accessKeyId: process.env.HW_KEY!, secretAccessKey: process.env.HW_SECRET!,},}exportfunctiongetS3(vendor: Vendor){returnnew S3Client(config[vendor])}// 用法 const oss=getS3("aliyun")await oss.write("hello.txt","兄弟们好啊")

**业务代码只调getS3("aliyun")，**内部云厂商怎么换，外面一行不用改。

读文件：text / json / stream

S3Client.file()返回的S3File继承自Blob。

跟Bun.file用法一模一样：

import{S3Client}from"bun"const oss=new S3Client({accessKeyId: process.env.ALI_KEY!, secretAccessKey: process.env.ALI_SECRET!, bucket:"my-bucket", endpoint:"https://oss-cn-hangzhou.aliyuncs.com",})// 读 JSON const data=await oss.file("user.json").json()// 读字符串 const text=await oss.file("readme.txt").text()// 读字节 const bytes=await oss.file("image.png").bytes()// 大文件流式读 const stream=oss.file("big.log").stream()forawait(const chunk of stream){process.stdout.write(chunk)}

流式读省内存，GB 级日志不爆掉。

写文件：fetch 响应直接转存

write()第二个参数接 Response，能直接把网络资源存到云：

import{S3Client}from"bun"const oss=new S3Client({accessKeyId: process.env.ALI_KEY!, secretAccessKey: process.env.ALI_SECRET!, bucket:"my-bucket", endpoint:"https://oss-cn-hangzhou.aliyuncs.com",})// 下载网络图片直接存到阿里 OSS const res=await fetch("https://example.com/photo.jpg")await oss.write("uploads/photo.jpg", res)

没用 Bun 之前你得这么写：

// 老套路：先下到内存，再上传 const res=await fetch("https://example.com/photo.jpg")const buffer=Buffer.from(await res.arrayBuffer())await oss.put("uploads/photo.jpg", buffer)

Bun 直接把 fetch 响应流过去，零内存拷贝。

presign URL：临时直传

最香的功能，前端直传云端，文件不过你服务器。

import{S3Client}from"bun"const oss=new S3Client({accessKeyId: process.env.ALI_KEY!, secretAccessKey: process.env.ALI_SECRET!, bucket:"my-bucket", endpoint:"https://oss-cn-hangzhou.aliyuncs.com",})//10分钟过期的上传链接 const uploadUrl=oss.file("uploads/avatar.jpg").presign({method:"PUT", expiresIn:600, type:"image/jpeg", acl:"public-read",})// 把这个 URL 发给前端 console.log("前端用这个 URL PUT 即可：", uploadUrl)

前端代码：

// 前端 constfile=document.querySelector("input").files[0]await fetch(uploadUrl,{method:"PUT", body: file, headers:{"Content-Type":"image/jpeg"},})

这套东西做用户上传头像、资料文件省到爆。

服务器只发 URL，**文件流直接从浏览器到云，**省一大笔 CDN 流量费。

三家云都能用，签名算法走 AWS v4 通用规范。

列文件 & 删文件

管理后台经常要清旧文件：

import{S3Client}from"bun"const oss=new S3Client({accessKeyId: process.env.ALI_KEY!, secretAccessKey: process.env.ALI_SECRET!, bucket:"my-bucket", endpoint:"https://oss-cn-hangzhou.aliyuncs.com",})// 列前100个 uploads/ 下的文件 const list=await oss.list({prefix:"uploads/", maxKeys:100})for(const obj of list.contents ??[]){console.log(`${obj.key}→ ${obj.size}字节`)}// 分页if(list.isTruncated){const next=await oss.list({prefix:"uploads/", startAfter: list.contents!.at(-1)!.key,})}// 判断文件是否存在 const exists=await oss.exists("uploads/1.png")// 删除 await oss.delete("uploads/old.txt")

**同一套 API，三家云都能用，**写一次列文件逻辑，永远不用重写。

性能：比 aws-sdk 快 10 倍

Bun 官方测试，相同硬件、相同网络：

|
场景
|
Bun.S3
|
aws-sdk v3
|
| :-- | :-- | :-- |
|
小文件读取
|
3.2 GB/s
|
0.3 GB/s
|
|
大文件流式读
|
1.8 GB/s
|
0.2 GB/s
|
|
小文件上传
|
1.5 GB/s
|
0.15 GB/s
|

快 10 倍左右。

Bun 用 Zig 写了底层 HTTP 客户端，跳过 Node 的 V8 + libuv 老路。

**冷启动也从 80MB 降到 0，**因为Bun.S3Client是内置的，不占 node_modules。

避坑指南

兄弟们，有几个坑先说在前面：

1. 签名 region 别瞎写

阿里 OSS 用oss-cn-hangzhou，腾讯 COS 用ap-guangzhou，华为 OBS 用cn-north-4，AWS 用us-east-1。

各家格式不一样，照搬必报错。

2. 腾讯 COS 的 bucket 带 APPID

my-bucket-1250000000，1250000000这串数字不能少。

3. 阿里 OSS 的 ACL 字段值有别

// 阿里 await oss.write("public.html", html,{acl:"public-read", type:"text/html",})

阿里、腾讯、华为三家 ACL 字符串基本通用，但个别值不一样，看云厂商文档。

4. path-style 和 virtual-host-style

AWS 默认用virtual-host-style：https://my-bucket.s3.amazonaws.com/key

阿里、腾讯、华为默认用path-style：https://oss-cn-hangzhou.aliyuncs.com/my-bucket/key

Bun 帮你自动处理，一般不用管。

5. Bun 版本

Bun ≥ 1.2.0才内置 S3 客户端。

bun--version# 1.3.x 就行

啥时候用 Bun.S3？

|
场景
|
推荐
|
| :-- | :-- |
|
新项目，团队用 Bun
|直接用 Bun.S3|
|
老项目 Node + aws-sdk
|
别动，稳定优先
|
|
国内多家云适配
|用 Bun.S3
，换 endpoint 就行
|
|
大文件（GB 级）流式处理
|用 Bun.S3
，自动分片
|
|
前端直传 / 临时下载链接
|用 Bun.S3
，presign 同步生成
|

总结

S3 这个协议，20 年前 AWS 搞出来，现在已经是行业事实标准。

国内三家：

• • 阿里 OSS 100% 兼容

• • 腾讯 COS 100% 兼容

• • 华为云 OBS 100% 兼容

国外一堆：

• • AWS S3 自己

• • Cloudflare R2

• • MinIO

• • Google Cloud Storage

• • DigitalOcean Spaces

学会 S3 API，一把钥匙开 10 把锁。

而 Bun 率先把 S3 焊死在运行时里，Bun.S3Client一个类通吃所有。

**比 aws-sdk 快 10 倍，****0 依赖、0 冷启动，**3 行代码搞定上传下载。

兄弟们，下次再有人问你 “怎么对接国内多家云存储”，直接把这篇甩给他，省你半小时口舌。

觉得有用？点个在看、转发。

评论区聊聊，你们公司在用哪家的对象存储？有没有被多云适配折腾过？