Bun-native: Thay Thế node:fs, node:path, node:url
Bản đồ từ node:fs, node:path, node:url sang API native của Bun như Bun.file(), Bun.write() và Bun.$ — cùng câu trả lời khi nào nên giữ nguyên Node.
Bạn có một codebase Node.js. Nó chạy ngon. Team muốn thử Bun vì khởi động nhanh hơn, test runner có sẵn trong runtime, và cài dependency chỉ mất vài giây thay vì vài phút.
Rồi bạn mở file đầu tiên và thấy mấy dòng này ở khắp nơi:
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const configPath = path.join(__dirname, "config.json");
const raw = fs.readFileSync(configPath, "utf8");tsCâu hỏi lóe lên ngay lập tức: “Có phải tôi phải viết lại tất cả không?”
Câu trả lời ngắn là không — và đây là điều quan trọng nhất cần hiểu về thiết kế của Bun. Bun không phải một hành tinh khác. Nó là hành tinh cũ với một chiếc thùng đồ nghề lớn hơn.
Câu trả lời trong 10 giây#
| Node.js | Bun thay thế | Có nên viết lại không? |
|---|---|---|
node:fs | Bun.file(), Bun.write(), Bun.$ | Chỉ khi đọc/ghi nội dung file đơn giản |
node:path | path / node:path | Không — giữ nguyên là được |
node:url | URL, URLSearchParams (Web API) | Chỉ khi bạn thực sự muốn dùng Web API |
node:child_process | Bun.$, Bun.spawn | Tùy chọn, khá đẹp cho lệnh shell |
Mô hình tư duy: thùng đồ nghề lớn hơn, chứ không phải thùng đồ nghề khác#
Hãy dùng hình ảnh này để toàn bộ chủ đề trở nên dễ hiểu.
Hãy tưởng tượng bạn đứng trong xưởng mộc. Node.js trao cho bạn một chiếc thắt lưng đồ nghề gồm búa, cưa và tua nha. Rồi Bun xuất hiện và nói: “Đây là chiếc búa tốt hơn, cưa điện và máy đo laser — à, và chiếc búa cũ vẫn dùng được bình thường.”
Có công cụ mới không có nghĩa bạn phải thay cái cũ. Nó có nghĩa là bạn giờ có lựa chọn, và nên dùng công cụ mới khi nó thực sự làm code của bạn dễ đọc hơn.
Lớp tương thích của Bun được thiết kế rất sâu. node:fs, node:path, node:url, node:http cùng hàng trăm module khác chạy trên Bun với đúng ngữ nghĩa như Node. Đó chính là điểm mấu chốt: phần lớn code Node hiện có chạy không cần sửa một dòng nào.
[!TIP] Hãy xem API native của Bun là lối nâng cấp, không phải yêu cầu migrate. Bạn có thể áp dụng từng file một, vào đúng lúc code trở nên dễ đọc hơn.
1. node:fs → Bun.file() và Bun.write()#
Trao đổi cơ bản#
// Node
import fs from "node:fs";
const text = fs.readFileSync("file.txt", "utf8");
fs.writeFileSync("file.txt", "hello");ts// Bun
const text = await Bun.file("file.txt").text();
await Bun.write("file.txt", "hello");tsĐó là toàn bộ ý tưởng: Bun.file(path) trả về một file handle (thực chất là BunFile, tuân thủ chuẩn Blob của Web), còn Bun.write(destination, data) ghi mọi thứ xuống đĩa.
Kiểm tra file có tồn tại không#
const exists = await Bun.file("file.txt").exists();tsDễ chịu hơn nhiều so với mẹo quen thuộc trong Node: try { fs.accessSync(p) } catch { false }.
[!WARNING]
Bun.file()là thao tác lazy — tạo handle không hề chạm vào đĩa và không bao giờ throw, kể cả khi file không tồn tại. Một file không tồn tại sẽ báosize === 0vàtype === "text/plain;charset=utf-8". Lỗi chỉ xuất hiện khi bạn thực sự đọc nó (ENOENT: no such file or directory). Vì vậy, hãy dùng.exists()khi cần kiểm tra sự tồn tại, đừng coiBun.file()là một bước kiểm tra.
Đọc JSON#
const data = await Bun.file("config.json").json();tsKhông còn JSON.parse(fs.readFileSync(...)) nữa. .json() parse sẵn cho bạn.
Mọi thứ một BunFile làm được#
const file = Bun.file("data.bin");
await file.text(); // string
await file.json(); // JSON đã parse
await file.arrayBuffer(); // ArrayBuffer
await file.bytes(); // Uint8Array
file.stream(); // ReadableStream
await file.exists(); // boolean
await file.delete(); // xoá filetsVì một BunFile chính là một Blob, nó có thể đưa thẳng vào fetch, Response, hoặc bất kỳ API nào nhận dữ liệu nhị phân.
Ghi file#
Bun.write() là một công cụ đa năng. Đích có thể là đường dẫn, URL file:// hoặc một BunFile; dữ liệu có thể là string, Blob, ArrayBuffer, typed array, hay thậm chí là body của một Response.
await Bun.write("output.txt", "plain text");
await Bun.write("output.txt", new Uint8Array([1, 2, 3]));
// Copy file — Bun tự chọn syscall nhanh nhất theo từng nền tảng
await Bun.write(Bun.file("copy.txt"), Bun.file("input.txt"));
// Tải thẳng về đĩa
const response = await fetch("https://bun.com");
await Bun.write("index.html", response);
// Đẩy nội dung file ra stdout
await Bun.write(Bun.stdout, Bun.file("input.txt"));tsBun.write() resolve với số byte đã ghi, rất tiện để log:
const bytes = await Bun.write("output.txt", "hello");
console.log(`wrote ${bytes} bytes`); // wrote 5 bytestsGhi dần bằng FileSink#
Khi file quá lớn để nạp vào RAM, hãy dùng writer:
const writer = Bun.file("output.txt").writer();
writer.write("it was the best of times\n");
writer.write("it was the worst of times\n");
await writer.end(); // flush + đóng filets[!NOTE] Một khác biệt hành vi đáng lưu tâm:
Bun.write()tự tạo thư mục cha nếu chưa có, trong khifs.writeFileSync()của Node sẽ némENOENTkhi thư mục cha không tồn tại. Đã kiểm chứng trên Bun 1.4.3 —Bun.write("a/b/c.txt", "x")thành công và tự tạo cảa/b/.
node:fs vẫn nắm giữ những gì?#
Bun.file() giải quyết nội dung file. Nó không giải quyết hệ thống file. Với những thao tác dưới đây, hãy giữ node:fs — bản implementation của Bun rất nhanh:
import { mkdir, readdir, stat } from "node:fs/promises";
// Tạo cây thư mục
await mkdir("build/output", { recursive: true });
// Liệt kê file
const entries = await readdir(import.meta.dir, { recursive: true });
// Lấy metadata
const info = await stat("package.json");
console.log(info.size, info.mtime);tsChính tài liệu của Bun nói thẳng: for operations they don’t cover, such as mkdir or readdir, use Bun’s nearly complete implementation of the node:fs module.
Và lối thoát hiểm cho shell: Bun.$#
Đọc ghi file không phải là toàn bộ I/O trong code của bạn. Thỉnh thoảng bạn cần chạy một lệnh:
// Node
import { execSync } from "node:child_process";
execSync("git rev-parse HEAD");ts// Bun
import { $ } from "bun";
const hash = await $`git rev-parse HEAD`.text();tsBun.$ là một shell giống bash, cross-platform, được viết bằng Rust. Nó không phải là wrapper quanh /bin/sh — đây là một bản cài lại, chạy ngay trong tiến trình Bun, nên hành vi giống nhau trên Windows, macOS và Linux.
await $`ls -la`.quiet(); // không in ra gì
await $`echo "hi"`.text(); // "hi\n"
await $`cat package.json`.json(); // JSON đã parse
for await (const line of $`cat list.txt`.lines()) { /* ... */ }tsVà một chi tiết bảo mật rất đáng lưu tâm: giá trị nội suy được escape mặc định, nên input từ người dùng không thể thoát ra ngoài lệnh.
const userInput = "my-file.txt; rm -rf /";
await $`ls ${userInput}`; // ls nhận MỘT tham số nguyên chữ, không phải hai lệnhtsKhi cần kiểm soát tiến trình đầy đủ (pipe stdin/stdout, biến môi trường, exit code), hãy dùng Bun.spawn:
const proc = Bun.spawn(["echo", "hello"], { stdout: "pipe" });
const output = await new Response(proc.stdout).text();
await proc.exited;
console.log(output, proc.exitCode);ts2. node:path → cứ giữ nguyên#
import path from "node:path";
const file = path.join("src", "index.ts");
const dir = path.dirname(file);
const ext = path.extname(file);
const abs = path.resolve(file);tsKhông có lợi ích gì khi thay thế node:path trong Bun:
- Nó chỉ là logic xử lý chuỗi — không I/O, không magic runtime.
- Nó nhận biết nền tảng (dấu phân cách Windows, ổ đĩa, đường dẫn UNC).
- Bun cài đặt đầy đủ và vượt qua chính bộ test của Node cho module này.
- Thay bằng nối chuỗi thủ công là một cú hạ cấp, không phải nâng cấp.
Một tiện ích riêng của Bun là biết file này nằm ở đâu:
import.meta.dir; // "/a/b" — đường dẫn tuyệt đối của thư mục chứa file này
import.meta.path; // "/a/b/c.ts" — đường dẫn tuyệt đối của file nàytsHãy so sánh với process.cwd() — nơi lệnh được chạy, chứ không phải nơi code nằm. import.meta.dir là câu trả lời của Bun cho bài toán kinh điển “làm sao tìm file nằm cạnh module của mình?”.
[!NOTE] Node.js cũng đã bắt kịp: từ Node 20.11 / 21.2,
import.meta.dirnamevàimport.meta.filenametrở thành chuẩn. Nên nếu muốn code chạy được trên cả hai runtime,import.meta.dirnamelà cách viết portable, cònimport.meta.dirlà bản riêng của Bun.
3. node:url → ưu tiên Web API chuẩn#
Lớp URL không phải phát minh của Bun — đó là chuẩn Web, có mặt trong trình duyệt, Node, Deno, Bun, worker, mọi nơi.
const url = new URL("https://example.com/foo?bar=baz");
console.log(url.pathname); // "/foo"
console.log(url.searchParams.get("bar")); // "baz"
console.log(url.host); // "example.com"tsURLSearchParams là cách dựng query string gọn gàng:
const params = new URLSearchParams({ page: "2", q: "bun runtime" });
console.log(`https://api.example.com/search?${params}`);tsVới trường hợp rất phổ biến là “đổi URL của module thành đường dẫn trên đĩa”, Node cần một hàm phụ:
import { fileURLToPath } from "node:url";
const filename = fileURLToPath(import.meta.url);tsTrong Bun, thường bạn không cần hàm phụ nào:
const filename = import.meta.path;
const dirname = import.meta.dir;tsfileURLToPath() vẫn chạy được trong Bun (qua node:url) và vẫn là công cụ đúng khi bạn cần chuyển một URL file:// bất kỳ, không chỉ import.meta.url:
const localPath = fileURLToPath(new URL("../config/app.json", import.meta.url));tsCó nên viết lại? Cây quyết định#
Lộ trình migrate không gây đau#
- Trước tiên, đừng làm gì cả. Đổi
nodethànhbuntrong Dockerfile/CI rồi chạy test suite. Hầu hết code pass nguyên vẹn. - Thay cái rườm rà, đừng thay logic. Đổi
fs.readFileSync+JSON.parsethànhawait Bun.file(p).json()— đây là cải thiện khả năng đọc, không phải viết lại. - Dùng
Bun.$cho các lệnh shell đang làexecSync— bạn được thêm escaping và hành vi cross-platform miễn phí. - Để yên
node:pathvànode:urltrừ khi bạn thực sự muốn dùng WebURLAPI. - Giữ
node:fscho phần thư mục và quyền — bảnnode:fscủa Bun rất nhanh và sẽ không biến mất.
Những cái bẫy đáng nhớ#
Bun.file()không bao giờ throw với file thiếu. Nó là một promise, không phải một check. Hãy dùng.exists().Bun.write()trả về số byte, và tự tạo thư mục cha nếu thiếu.Bun.file()nhận path, file descriptor, hoặc URLfile://:Bun.file(new URL(import.meta.url)).import.meta.path/import.meta.dirchỉ có ở Bun;import.meta.urlmới là bản portable.- Các API đồng bộ của
node:fsvẫn chạy tốt trong Bun. Chúng nhanh. “Async everywhere” là lựa chọn phong cách, không phải yêu cầu. - Đừng dùng
Bun.file()cho thư mục — nó dành cho nội dung file.
TL;DR#
Nếu mục tiêu của bạn là tương thích với Bun, đừng viết lại tất cả:
node:fs → Bun.file / Bun.write khi bạn muốn API native của Bun
node:path → giữ node:path
node:url → URL / URLSearchParams, hoặc giữ node:url khi cầntextBun được thiết kế để chạy phần lớn code Node.js hiện có mà không cần thay đổi. Hãy dùng API native của Bun ở nơi chúng làm code dễ hiểu hơn, còn lại thì để nguyên.
Tài liệu tham khảo#
- Bun Documentation — File I/O ↗
- Bun Documentation — Shell ↗
- Bun Documentation — Node.js Compatibility ↗
- Bun Documentation —
import.meta.dir↗ - Bun API Reference —
Bun.write()↗ - Node.js Documentation —
node:path↗ - Node.js Documentation —
node:url↗ - Node.js Documentation —
import.meta.dirname↗ - MDN —
URL↗