Bun 1.3 のプロジェクトを 1.4 に上げたら動かなくなったときの直し方
この記事が解決する悩みです。
- Bun 1.3 で動いていた API サーバーが 1.4 にした瞬間 TypeError を吐く
- stream の read() の返り値が変わって、データが途中までしか届かなくなった
- bun:ffi の CString が使えなくなり、メモリ解放の書き方が通らない
- bunfig.toml をいじっていないのに起動時に SyntaxError になる
対象読者: Bun で作ったツールや社内サーバーを 1.3 で運用している人です。
前提知識: Bun の基本操作と、Node.js の http / stream の基礎が分かることです。
結論
Bun 1.3 から 1.4 への移行で、実際のプロジェクトで壊れたのは4箇所でした。まとめると次の通りです。
| 壊れた箇所 | 1.3 の挙動 | 1.4 の挙動 | 直し方 |
|---|---|---|---|
| res.writeHeader() | 動く | TypeError | res.writeHead() に置き換える |
| paused read() | バッファ全体を返す | 1チャンクだけ返す | ループで read() する |
| bun:ffi の CString | .ptr が取れる | 文字列になり .ptr が無い | ポインタを別途保持する |
| bunfig.toml | 曖昧でも動く | 厳格な TOML で SyntaxError | 文字列を引用符で囲む |
どれも「書き方の問題」なので、1.3 のコードを直せば 1.4 でもそのまま動きます。ロジックの書き換えは不要ですよ。
移行の進め方
結論から言うと、まずバージョンを上げてから壊れた箇所を直すのが早いです。
今回移行したのは、node:http で小さな API サーバーを出しているツールと、stream でファイルを捌くバッチの2本です。テストは薄めなので、実質の検証は「起動してリクエストを打つ」でした。
手順は次の3つだけです。
- bun upgrade で最新の 1.4 に上げる
- bun –version と bun.lock の有無を確認する
- テストと起動スクリプトを回してエラーを拾う
1.4 は 2026-08-20 に出ていて、私が検証した時点の最新は 1.4.4 でした。破壊的変更の一覧は公式のリリースノートの Upgrading to 1.4に書かれています。
既存の bun.lock を持つプロジェクトは linker の挙動が変わりません。新規 monorepo だけ isolated linker が既定になる点だけ押さえておけば大丈夫です。
壊れた箇所1: res.writeHeader() が消えた
node:http 互換のサーバーで、1.3 まで使えた res.writeHeader() が 1.4 で消えました。
再現したコードがこちらです。1.3 時代に普通に書いていた形ですね。
import { createServer } from "node:http";
const server = createServer((req, res) => {
// Bun 1.3 では動いていた書き方
res.writeHeader(200, { "Content-Type": "text/plain" });
res.end("hello from bun-migration-demo");
});
server.listen(3461, () => {
console.log("listening on 3461");
});
// --- Bun 1.3.14 で実行 ---
// # 実行結果
// curl で "hello from bun-migration-demo" が返る
// --- Bun 1.4.4 で実行 ---
// # 実行結果
// TypeError: res.writeHeader is not a function.
// (In 'res.writeHeader(200, { "Content-Type": "text/plain" })', 'res.writeHeader' is undefined)
直し方は1行で、writeHead に置き換えるだけです。
const server = createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("hello from bun-migration-demo");
});
// # 実行結果 (Bun 1.4.4)
// curl で "hello from bun-migration-demo" が返る
理由は単純で、Bun 1.4 が報告する Node.js 互換レベルが 26 になり、writeHeader() ごと削除されたからです。
直し方は分かっているので、あとは一括置換です。対象の検索だけ載せておきます。
grep -rn "writeHeader" src/
このプロジェクトでは1箇所だけでした。writeHead への置換は名前の違いだけなので、機械的に直せます。
壊れた箇所2: paused read() が1チャンクだけ返す
stream を paused モードで read() すると、1.3 ではバッファ全体が一気に返っていました。
1.4 では「1回の read() で1チャンクだけ」に変わったので、ループ前提のコードはデータ欠けします。
import { Readable } from "node:stream";
const r = new Readable({
read() {},
});
r.push("chunk-1");
r.push("chunk-2");
r.push("chunk-3");
const first = r.read(); // 引数なしの paused read
console.log("read() 1回目:", JSON.stringify(first));
console.log("read() 2回目:", JSON.stringify(r.read()));
// # 実行結果 (Bun 1.3.14)
// read() 1回目: {"type":"Buffer","data":[99,104,117,110,107,45,49,99,104,117,110,107,45,50,99,104,117,110,107,45,51]}
// read() 2回目: null
// # 実行結果 (Bun 1.4.4)
// read() 1回目: {"type":"Buffer","data":[99,104,117,110,107,45,49]}
// read() 2回目: {"type":"Buffer","data":[99,104,117,110,107,45,50]}
1.3 では3チャンク分が1回目にまとめて入っていました。1.4 では chunk-1、chunk-2 と1つずつしか返りません。
直し方は、null が返るまで read() を回すことです。EOF まで回した実測がこちらです。
import { Readable } from "node:stream";
const r = new Readable({
read() {},
});
r.push("chunk-1");
r.push("chunk-2");
r.push("chunk-3");
r.push(null); // EOF
let chunk;
const all: string[] = [];
while ((chunk = r.read()) !== null) {
all.push(chunk.toString());
}
console.log("集まったチャンク:", all);
// # 実行結果 (Bun 1.4.4)
// 集まったチャンク: [ "chunk-1", "chunk-2", "chunk-3" ]
引数でサイズを明示する書き方でも同じです。どちらにしても「1回で全部取れる」前提は捨てるのがポイントです。
壊れた箇所3: bun:ffi の CString が .ptr を持たない
ネイティブライブラリを呼ぶ bun:ffi でも挙動が変わりました。詳細は公式の ffi ドキュメントに沿った話です。
1.3 では new CString(ptr) が CString オブジェクトを返して .ptr が取れました。1.4 ではプレーンな文字列になるため、.ptr が undefined になります。
import { dlopen, CString } from "bun:ffi";
const lib = dlopen("demo.dll", {
// 生ポインタを受け取る定義 (1.3 時代の書き方)
greet: { args: [], returns: "ptr" },
});
const str = new CString(lib.symbols.greet());
console.log("greet() =", str.toString());
console.log("typeof str.ptr =", typeof (str as any).ptr);
// # 実行結果 (Bun 1.3.14)
// greet() = hello from demo.dll
// typeof str.ptr = number
// # 実行結果 (Bun 1.4.4)
// greet() = hello from demo.dll
// typeof str.ptr = undefined
直し方は、dlopen 側で生ポインタを受け取った時点で保持しておくことです。文字列化した後に .ptr を引き戻せる前提は捨てましょう。
native ライブラリを長時間使い回すサーバーほど、解放用ポインタを取りこぼすとメモリリークにつながります。ffi を使っているプロジェクトは優先的に見ておくのが安全です。
壊れた箇所4: bunfig.toml が厳格な TOML になった
最後は設定ファイル側です。引用符なしの文字列を許していたパーサーが、1.4 で厳格な TOML になりました。
# bunfig.toml (移行前から置いてあったもの)
[install]
linker = hoisted
$ bun show-env.ts
# # 実行結果 (Bun 1.3.14)
# API_KEY = (undefined) --> 起動できた
# # 実行結果 (Bun 1.4.4)
# error: Strings must be quoted
# at .../bunfig.toml:2:10
# SyntaxError: failed to load bunfig
1.4 では起動そのものが止まります。直し方は文字列を引用符で囲むだけです。
[install]
linker = "hoisted"
TOML には check 用のコマンドが無いので、移行前に bunfig.toml の中身を目視で1回見直すのが確実です。
なお、公式ノートによると同じ厳格化は Bun.TOML や Bun.YAML を実行時に読むコード側にも及びます。設定を動的に生成しているツールは、こちらも合わせて確認してください。
つまずきポイント
ネイティブアドオンを使っているプロジェクトは、別途 ABI の確認が必要です。実測した値がこちらです。
$ bun -e 'console.log("modules =", process.versions.modules)'
# # 実行結果 (Bun 1.3.14)
# modules = 137
# # 実行結果 (Bun 1.4.4)
# modules = 147
prebuilt バイナリを配るパッケージは 147 向けのビルドがあるか確認してください。bun install 時に落ちるのではなく、ロード時にエラーになるタイプの問題です。
あと1点だけ、公式ノートに「node 経由で呼んだとき .env が読まれない」とありましたが、手元の bun –bun では 1.3・1.4 どちらも .env が読まれたので、こちらは再現できていません。node へのシンボリックリンク経由で呼んでいる場合だけ確認してみてください。
検証環境
| OS | Windows 11 (build 10.0.26200) |
|---|---|
| CPU | AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics |
| メモリ | 28GB |
| 言語/ツール | Bun 1.3.14 / Bun 1.4.4(GitHub Releases の公式 bun-windows-x64.zip を一時ディレクトリに展開)/ rustc 1.95(demo.dll のビルド用) |
| 使用コマンド | bun –version / bun server.ts(node:http サーバに curl でリクエスト)/ bun stream.ts / bun ffi-demo.ts / bun show-env.ts(bunfig.toml 厳格化の確認) |
| 測定日 | 2026-11-10 |
上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。

まとめ
Bun 1.3 から 1.4 の移行で、実測で壊れたのは http・stream・ffi・設定ファイルの4箇所でした。全部「書き方を直せば戻る」系なので、恐怖はないですね。
移行のコツは1つです。テストを先に回して、writeHeader と read() を grep する。
今回の実行結果はすべて検証環境に記した通り、Bun 1.3.14 と 1.4.4 の両方で実際に動かして確かめています。
参考
- Bun 1.4 リリースノート(公式)— Upgrading to 1.4 の破壊的変更一覧
- Bun v1.4.4 リリースノート(公式)— 検証時点の最新パッチ
- bun:ffi ドキュメント(公式)
- oven-sh/bun Releases(GitHub)
あわせて読みたい
- 【OSS】Bun 1.4 完全ガイド — Rust 書き換えと新APIの使い方
- 【pnpm】ERR_PNPM_IGNORED_BUILDS の直し方 — allowBuilds へ移行
- 【JS・フロントエンド】ERR_UNSUPPORTED_TYPESCRIPT_SYNTAXの直し方
この記事を書いた人: Kurosaki.Ren。記事のコードは隔離した環境で実行してから掲載しています。詳しいプロフィールは著者プロフィールページへどうぞ。
【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう!!![]()

コメント