Bun.s3でAWS EmulatorのS3を読み書きする方法
Bun の Bun.s3 は、S3_ACCESS_KEY_ID、S3_ENDPOINT などの環境変数と、証明書の設定を足せば、手元で動かす AWS Emulator の S3 を読み書きできます。AWS のアカウントを使わずに、S3 にファイルを置くコードをローカル環境や CI でテストしたいときの手順です。AWS CLI 用の設定だけでは動かない理由と、足りない設定を、検証環境で実行した出力つきで示します。
検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4、AWS Emulator 1.0.385(2026年11月14日リリース)、AWS CLI 2.40.3 です。AWS のアカウントと認証情報は使っていません。本物の S3 での動き(料金、速さなど)は確かめておらず、本物の S3 について書いているところは公式ドキュメントを出どころにしています。コードは TypeScript のファイルを bun でそのまま実行しました。エミュレーターを起動し直したときの動きは試しておらず、公式ドキュメントをもとに書いています。
エミュレーターを起動して、バケットを作っておく
AWS Emulator の入れ方は、公式の Linux 向けの手順のとおりです。aws-emulator -t off で起動します(-t off はテレメトリーを切る指定)。エミュレーターは https://127.0.0.1:9297 で待ち受け、~/.aws/emulator/9297/ に、その起動でだけ使えるアクセスキー(emulator_credentials)と証明書(ca.pem)を書き出します。
別の端末で、公式ドキュメントにある AWS CLI と SDK 向けの環境変数を設定し、読み書きに使うバケットを AWS CLI で作っておきます。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
$ aws s3api create-bucket --bucket example-bucket
{
"Location": "/example-bucket",
"BucketArn": "arn:aws:s3:::example-bucket"
}
AWS CLI 用の環境変数だけでは、Bun.s3 は動かない
この状態で、Bun.s3 からファイルを置いてみます。no-creds.ts に次のコードを書きました。
// AWS CLI 用の環境変数だけで Bun.s3 を使ってみる
import { s3 } from "bun";
try {
await s3.file("hello.txt", { bucket: "example-bucket" }).write("hello");
} catch (e) {
console.log(e.name, e.code, "-", e.message);
}
$ bun no-creds.ts
S3Error ERR_S3_MISSING_CREDENTIALS - Missing S3 credentials. 'accessKeyId', 'secretAccessKey', 'bucket', and 'endpoint' are required
認証情報がないというエラーです。Bun の公式ドキュメントによると、Bun.s3 が読むのは次の環境変数で、S3_ で始まるものがなければ AWS_ で始まるものを読みます。
| 設定 | 先に読む変数 | なければ読む変数 |
|---|---|---|
| アクセスキーID | S3_ACCESS_KEY_ID |
AWS_ACCESS_KEY_ID |
| シークレットアクセスキー | S3_SECRET_ACCESS_KEY |
AWS_SECRET_ACCESS_KEY |
| リージョン | S3_REGION |
AWS_REGION |
| 接続先 | S3_ENDPOINT |
AWS_ENDPOINT |
| バケット | S3_BUCKET |
AWS_BUCKET |
| セッショントークン | S3_SESSION_TOKEN |
AWS_SESSION_TOKEN |
表には、AWS_SHARED_CREDENTIALS_FILE が指す認証情報ファイルも、AWS CLI の AWS_ENDPOINT_URL も入っていません。エミュレーターのアクセスキーと接続先は、この表の変数に入れ直す必要があります。

アクセスキーとバケットを S3_ の変数に入れる
アクセスキーは、aws configure get で emulator_credentials から取り出せます。入れる先は AWS_ACCESS_KEY_ID ではなく S3_ACCESS_KEY_ID にしました。同じシェルの AWS CLI に影響させないためです。AWS Emulator の公式ドキュメントによると、アクセスキーの環境変数は認証情報ファイルより優先されます。
export S3_ACCESS_KEY_ID=$(aws configure get aws_access_key_id)
export S3_SECRET_ACCESS_KEY=$(aws configure get aws_secret_access_key)
export S3_BUCKET=example-bucket
AWS_SHARED_CREDENTIALS_FILE が emulator_credentials を指しているので、検証環境では20文字のアクセスキーIDと40文字のシークレットアクセスキーが取り出せました。リージョンは、すでに設定した AWS_REGION(us-east-1)が読まれます。
接続先がどこになるかは、署名付き URL を作る presign() で確かめられます。Bun のドキュメントによると、presign() は手元で URL を組み立てるだけで、通信はしません。where.ts に次のコードを書きました。
// 接続先がどこになるかを、通信しない presign() で確かめる
import { s3 } from "bun";
const url = new URL(s3.file("hello.txt").presign({ expiresIn: 60 }));
console.log(url.origin + url.pathname);
AWS_ENDPOINT_URL しか設定していない状態では、接続先は本物の S3 になっていました。
$ bun where.ts
https://s3.us-east-1.amazonaws.com/example-bucket/hello.txt
S3_ENDPOINT(または AWS_ENDPOINT)を設定し忘れると、Bun.s3 の送り先は本物の S3 になります。AWS Emulator の公式ドキュメントも、テストを動かすシェルで接続先が設定されていないと、見つかった認証情報で AWS を呼び出してしまうと注意しています。本物の認証情報を、テストを動かす環境に置かないようにします。
S3_ENDPOINT を設定すると、エミュレーターに向きました。バケット名はホスト名ではなくパスに入っています。AWS Emulator の公式ドキュメントでは、バケット名をホスト名に入れたリクエストはエミュレーターが受け付けないとされています。Bun では virtualHostedStyle を指定しなければ、この形のまま送られます。
$ export S3_ENDPOINT=https://127.0.0.1:9297
$ bun where.ts
https://127.0.0.1:9297/example-bucket/hello.txt
証明書は NODE_EXTRA_CA_CERTS か SSL_CERT_FILE で渡す
接続先が決まったので、書いて読み戻すコードを hello.ts に書いて動かします。
import { s3 } from "bun";
try {
const file = s3.file("hello.txt");
const bytes = await file.write("こんにちは、S3");
console.log("write:", bytes, "bytes");
console.log("text:", await file.text());
} catch (e) {
console.log(e.name, e.code, "-", e.message);
}
AWS Emulator の証明書についての説明のとおり、エミュレーターは自分で作った証明書で HTTPS を受け付けるので、そのままでは証明書のエラーになりました。AWS CLI 用の AWS_CA_BUNDLE が設定してあっても、結果は同じです。
$ bun hello.ts
S3Error DEPTH_ZERO_SELF_SIGNED_CERT - an unexpected error has occurred
NODE_EXTRA_CA_CERTS に ca.pem のパスを設定すると、書いて読み戻せました。SSL_CERT_FILE でも同じ結果でした。
$ NODE_EXTRA_CA_CERTS=~/.aws/emulator/9297/ca.pem bun hello.ts
write: 20 bytes
text: こんにちは、S3
$ SSL_CERT_FILE=~/.aws/emulator/9297/ca.pem bun hello.ts
write: 20 bytes
text: こんにちは、S3
write() が返した 20 は、UTF-8 にしたときのバイト数です(この文字列のかなと読点は、UTF-8 で1文字3バイトです)。Bun の環境変数の一覧では、SSL_CERT_FILE は、Bun がもともと持っているルート証明書に加えて信頼する証明書のファイルと説明されています。以降は NODE_EXTRA_CA_CERTS を設定したシェルで進めました。
Bun で置いたファイルは、AWS CLI からも見えます。
$ aws s3 ls s3://example-bucket/
2026-11-15 09:09:28 20 hello.txt
$ aws s3 cp s3://example-bucket/hello.txt -; echo
こんにちは、S3
まとめると、AWS CLI 用の設定に次の4行を足せば、Bun.s3 をエミュレーターに向けられます。
export S3_ACCESS_KEY_ID=$(aws configure get aws_access_key_id)
export S3_SECRET_ACCESS_KEY=$(aws configure get aws_secret_access_key)
export S3_ENDPOINT=https://127.0.0.1:9297
export NODE_EXTRA_CA_CERTS=~/.aws/emulator/9297/ca.pem
バケットは S3_BUCKET で決めるか、コードの中で s3.file("hello.txt", { bucket: "example-bucket" }) のように指定します。
JSON、文字列、バイト列を置いて読む
ここからは、いろいろな形のデータを置いて、読み方と情報の取り方を試します。readwrite.ts のコードです。
import { s3 } from "bun";
// JSON を Content-Type 付きで置く
const report = s3.file("reports/2026-11.json");
await report.write(JSON.stringify({ month: "2026-11", count: 3 }), {
type: "application/json",
});
// 文字列とバイト列も置く
await s3.write("notes/a.txt", "first note\n");
await s3.write("notes/b.bin", new Uint8Array([0, 1, 2, 3, 255]));
// 読む
console.log("json:", await report.json());
console.log("bytes:", await s3.file("notes/b.bin").bytes());
console.log("slice:", await s3.file("notes/a.txt").slice(0, 5).text());
// 情報を見る
console.log("stat:", await report.stat());
console.log("size:", await s3.size("notes/a.txt"));
console.log("exists:", await s3.exists("notes/a.txt"), await s3.exists("notes/zzz.txt"));
// 一覧
const all = await s3.list();
console.log("list keys:", all.contents?.map((o) => o.key), "keyCount:", all.keyCount, "isTruncated:", all.isTruncated);
const notes = await s3.list({ prefix: "notes/" });
console.log("prefix notes/:", notes.contents?.map((o) => `${o.key} ${o.size}`));
$ bun readwrite.ts
json: {
month: "2026-11",
count: 3,
}
bytes: Uint8Array(5) [ 0, 1, 2, 3, 255 ]
slice: first
stat: S3Stat {
etag: "\"4dffc5a16627d5f1df81e5f29d53a3b5\"",
lastModified: 2026-11-15T09:09:30.000Z,
size: 29,
type: "application/json;charset=utf-8",
}
size: 11
exists: true false
list keys: [ "hello.txt", "notes/a.txt", "notes/b.bin", "reports/2026-11.json" ] keyCount: 4 isTruncated: false
prefix notes/: [ "notes/a.txt 11", "notes/b.bin 5" ]
slice(0, 5) は先頭の5バイトだけを読みます。Bun のドキュメントの slice の説明によると、Bun は HTTP の Range ヘッダーで、その範囲だけを取りに行きます。stat() は、大きさ、ETag、更新日時、Content-Type を返しました。大きさだけなら size() でも取れます。Bun のドキュメントの size() と stat() の説明では、size() はファイルをダウンロードせずに大きさを調べる方法、stat() は大きさや ETag などのメタデータを取る方法として紹介されています。
type に application/json を指定したファイルは、Content-Type が application/json;charset=utf-8 になっていました。指定せずに文字列を置いた notes/a.txt は text/plain;charset=utf-8 です。AWS CLI で確かめても同じでした。
$ aws s3api head-object --bucket example-bucket --key reports/2026-11.json --query "{ContentType:ContentType,ContentLength:ContentLength}"
{
"ContentType": "application/json;charset=utf-8",
"ContentLength": 29
}
$ aws s3api head-object --bucket example-bucket --key notes/a.txt --query "{ContentType:ContentType,ContentLength:ContentLength}"
{
"ContentType": "text/plain;charset=utf-8",
"ContentLength": 11
}
存在しないキーやバケットを読んだときのエラー
読もうとしたキーやバケットがないときは、S3Error が投げられ、code に S3 のエラーの名前が入りました。missing.ts で試しました。
import { s3 } from "bun";
try {
await s3.file("no-such-key.txt").text();
} catch (e) {
console.log("name:", e.name, "code:", e.code);
console.log("message:", e.message);
}
try {
await s3.file("hello.txt", { bucket: "no-such-bucket" }).text();
} catch (e) {
console.log("name:", e.name, "code:", e.code);
console.log("message:", e.message);
}
$ bun missing.ts
name: S3Error code: NoSuchKey
message: The specified key does not exist.
name: S3Error code: NoSuchBucket
message: The specified bucket does not exist
ファイルがあるかどうかを確かめたいだけなら、try/catch でエラーを捕まえるより、さきほどの exists() で true か false を受け取るほうが簡単です。
署名付き URL で、curl から取り出す
presign() で作った URL には、エミュレーターの接続先と、X-Amz- で始まる署名用のクエリパラメーターが入っていました。presign.ts のコードと出力です。
import { s3 } from "bun";
const url = s3.file("reports/2026-11.json").presign({ expiresIn: 300 });
const u = new URL(url);
console.log(u.origin + u.pathname);
console.log([...u.searchParams.keys()].join("\n"));
$ bun presign.ts
https://127.0.0.1:9297/example-bucket/reports/2026-11.json
X-Amz-Algorithm
X-Amz-Credential
X-Amz-Date
X-Amz-Expires
X-Amz-Signature
X-Amz-SignedHeaders
この URL を curl に渡すと、認証情報なしで中身を取り出せました。curl にもエミュレーターの証明書を --cacert で渡します。
$ curl -s --cacert ~/.aws/emulator/9297/ca.pem "$(bun -e "console.log(Bun.s3.file(\"reports/2026-11.json\").presign({ expiresIn: 300 }))")"; echo
{"month":"2026-11","count":3}
12 MiB のファイルを置く
大きいファイルも試しました。12 MiB のバイト列を write() で置いたものと、writer() に partSize を 5 MiB と指定して 1 MiB ずつ書いたものです。large.ts のコードです。
import { s3 } from "bun";
// 12 MiB のデータを置く
const data = new Uint8Array(12 * 1024 * 1024).fill(97);
const file = s3.file("large/12mib.bin");
const t0 = performance.now();
await file.write(data);
console.log("write ms:", Math.round(performance.now() - t0));
const st = await file.stat();
console.log("size:", st.size, "etag:", st.etag);
// partSize を 5 MiB にして writer で送る
const w = s3.file("large/writer.bin").writer({ partSize: 5 * 1024 * 1024 });
for (let i = 0; i < 12; i++) w.write(new Uint8Array(1024 * 1024).fill(98));
await w.end();
const st2 = await s3.file("large/writer.bin").stat();
console.log("writer size:", st2.size, "etag:", st2.etag);
$ bun large.ts
write ms: 85
size: 12582912 etag: "f2dc0b2e7b392ea2f471bef4429d9df9"
writer size: 12582912 etag: "fbbee21746f5ddec0d42fa0af95d51f3-3"
どちらも 12,582,912 バイトで置けました。writer() で置いたほうは、ETag の最後に -3 が付いています。Python でデータを 5 MiB、5 MiB、2 MiB に分け、それぞれの MD5 をつないだものの MD5 を計算すると、この ETag と同じ値になりました。3つのパートに分けたマルチパートアップロードで送られたということです。write() で置いたほうの ETag は、12 MiB 全体の MD5 と同じ値でした。この大きさでは、分けずに1回で送られていました。公式ドキュメントの大きいファイルの例も、writer() に partSize と queueSize、retry を指定する書き方です。
削除する
delete() で消します。s3.file(...).delete() と s3.delete(キー) のどちらでも消せました。消したあとの exists() は false です。もう存在しないキーを delete() してもエラーにはなりませんでした。delete.ts のコードです。
import { s3 } from "bun";
await s3.file("notes/a.txt").delete();
await s3.delete("notes/b.bin");
console.log("exists after delete:", await s3.exists("notes/a.txt"), await s3.exists("notes/b.bin"));
// 無いキーを消す
await s3.delete("notes/a.txt");
console.log("delete missing key: no error");
console.log("left:", (await s3.list()).contents?.map((o) => o.key));
$ bun delete.ts
exists after delete: false false
delete missing key: no error
left: [ "hello.txt", "large/12mib.bin", "large/writer.bin", "reports/2026-11.json" ]
AWS Emulator の公式ドキュメントによると、エミュレーターを止めると、作ったリソースはすべて消えます。起動のたびにアクセスキーも作り直されるので、S3_ACCESS_KEY_ID と S3_SECRET_ACCESS_KEY は、起動のたびに aws configure get で入れ直します。AWS Emulator の証明書についての説明によると、ca.pem のパスを指す設定(NODE_EXTRA_CA_CERTS など)は、そのまま使えます。





