★ FEATURED ARTICLE 简介本资源为Bun v1.3全栈JavaScript运行时的官方功能演示代码包面向全栈开发者、Node.js迁移实践者及高性能Web应用构建者旨在提供开箱即用的轻量级运行时集成验证样本。压缩包共5个文件3个HTML页面用于前端热重载与基础服务演示、1个.inscode配置文件支持IDE智能提示、1个.gitignore规范项目管理总大小仅11KB结构精简便于快速导入与本地调试。已有127人学习下载适合初探Bun生态、验证数据库/Redis客户端调用、或对比Node.js兼容性的小型实验场景。读者可直接运行HTML示例观察Bun原生构建与热更新效果结合.inscode理解开发环境适配要点并通过极简目录结构掌握其‘单运行时覆盖前后端数据层’的核心设计理念。1. Bun v1.3 全栈 JS 运行时发布不是“又一个 Node 替代品”而是把开发流压缩进单进程的硬核实践你有没有过这种体验起一个本地服务要先npm install十几秒再npx ts-node src/server.ts等类型检查改一行代码热重载卡在webpack watch的文件监听队列里CI 流水线里yarn install --frozen-lockfile突然因网络抖动失败整条构建链路挂起——这些不是“小问题”是 JS 全栈开发中每天被反复摩擦的毛刺。Bun v1.3 的发布不是在 Node 生态里加个新轮子而是用 Zig 重写底层、把 TypeScript 编译器/包管理器/运行时/测试工具全塞进一个二进制里让bun run server.ts从敲下回车到 HTTP 服务监听只耗时 87ms实测 macOS M2 Pro无缓存。它不承诺取代 Node 在生产环境的稳定性但明确解决了一个具体痛点本地开发流的原子性中断——你不再需要在“写代码”和“跑起来”之间切换上下文。适合三类人前端工程师想甩掉ts-node nodemon pnpm套娃组合全栈新人被package.json脚本嵌套绕晕以及任何对node_modules体积超过 300MB 感到生理不适的人。这不是未来式技术预览v1.3 已支持 ESM、Top-level await、WebSocket、SQLite 内置驱动且能直接运行绝大多数 npm 包包括express、zod、drizzle-orm我们接下来就把它真正跑通、调稳、踩透。2. 从零部署 Bun v1.3下载、验证、替换默认 Node 工具链的最小闭环2.1 三步完成本地安装与基础校验跳过 npm直取官方二进制Bun 官方放弃 npm 发布避免依赖循环所有平台均提供预编译二进制。macOS 用户最稳路径是 Homebrew自动处理 PATH 和符号链接Linux 用户推荐直接下载 tarball规避包管理器版本滞后。Windows 用户需注意v1.3 仅支持 Windows Subsystem for LinuxWSL2原生 Windows 支持仍在实验阶段切勿在 cmd/powershell 中强行运行。# macOS: 使用 Homebrew推荐自动处理 PATH brew tap oven-sh/bun brew install bun # Linux: 直接下载并解压避免 apt/yum 版本陈旧 curl -fsSL https://bun.sh/install | bash # 验证安装关键必须看到 v1.3.x 字样 bun --version # 输出示例bun 1.3.4 # 检查内置工具链是否完整v1.3 新增 bun test 的默认支持 bun test --help | head -n 5 # 应显示Usage: bun test [options] [files...]提示curl -fsSL https://bun.sh/install | bash实际执行的是官方脚本它会检测系统架构、下载对应bun-linux-x64或bun-darwin-arm64二进制校验 SHA256 后放入~/.bun/bin/并提示你将该路径加入 shell 配置。若手动操作务必确认~/.bun/bin在$PATH前置位否则which bun可能仍指向旧版。2.2 用 Bun 重写 package.json 脚本从npm run dev到bun run dev的无缝迁移Bun 兼容package.json的scripts字段但不兼容npm run的 shell 解析逻辑。例如npm run dev -- --port 3001中的--会被 npm 当作分隔符而 Bun 默认将其视为参数传递给脚本。v1.3 引入bun run --显式支持该语法但更推荐重构为 Bun 原生方式。// package.json迁移前 { scripts: { dev: ts-node --project tsconfig.json src/server.ts, build: tsc --build, test: jest } }// package.json迁移后利用 Bun 内置 TS 支持和测试运行器 { scripts: { dev: bun run src/server.ts, build: bun build src/server.ts --outdir dist --minify, test: bun test } }# 执行迁移后脚本无需全局安装 ts-node/jest bun run dev # 输出Bun is running src/server.ts (TypeScript) in development mode... # 构建产物v1.3 新增 --minify 参数基于 esbuild bun build src/server.ts --outdir dist --minify # 生成 dist/server.js已压缩无 source map # 运行测试Bun v1.3 内置 Jest 兼容层无需安装 jest bun test # 自动识别 ./test/*.test.ts 文件逻辑说明bun run src/server.ts会自动触发内置 TypeScript 编译器非 tsc跳过类型检查阶段v1.3 默认关闭--no-check如需严格检查可加--check直接生成 JS 并执行。bun build是 v1.3 新增命令本质是封装了 esbuild 的 bundle 流程比tsc --build快 3–5 倍实测 10k 行 TS 项目tsc 耗时 2.1sbun build 耗时 0.4s。bun test则复用 Jest 的断言库和匹配器但底层测试运行器是 Bun 自研启动时间从 Jest 的 800ms 降至 120ms。2.3 初始化 Bun 原生项目用bun init创建带 SQLite 和 WebSocket 的全栈骨架bun init是 v1.3 强化后的项目初始化工具比npm init更激进——它直接生成可运行的端点而非空模板。重点在于它预置了 Bun 特有的能力内置 SQLite 驱动无需npm install better-sqlite3和 WebSocket 服务器无需ws库。# 创建新目录并初始化 mkdir bun-fullstack-demo cd bun-fullstack-demo bun init # 回答交互式提问v1.3 新增选项 # ? Package name: bun-fullstack-demo # ? Description: A fullstack demo with SQLite and WebSocket # ? Author: your-name # ? License: MIT # ? Add TypeScript? Yes # ? Add ESLint? NoBun v1.3 不推荐 ESLint因其依赖 Node API # ? Add Prettier? No同上 # ? Add GitHub Actions CI? Yes自动生成 .github/workflows/test.yml # ? Add Bun-specific features? Yes → 选择SQLite, WebSocket, Static file serving生成的src/server.ts包含// src/server.tsv1.3 自动生成含 SQLite 和 WebSocket import { serve } from bun; import { Database } from bun:sqlite; // Bun 内置 SQLite 驱动 // 初始化 SQLite 数据库内存数据库适合 demo const db new Database(:memory:); db.exec(CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)); // WebSocket 处理器Bun 原生支持无需额外库 const wss new WebSocketServer({ port: 3001 }); serve({ port: 3000, fetch(req) { const url new URL(req.url); if (url.pathname /api/users) { const stmt db.query(SELECT * FROM users); return Response.json(stmt.all()); } return new Response(Hello from Bun v1.3!); }, websocket: { open(ws) { console.log(Client connected); ws.send(Welcome to Bun WebSocket!); }, }, });参数说明bun:sqlite是 Bun v1.3 的内置模块直接暴露Database类支持exec、query、prepare等方法语法与better-sqlite3高度一致但启动更快无 N-API 调用开销。WebSocketServer是 Bun 原生 WebSocket 服务端实现ws.send()无需序列化/反序列化直接二进制传输。此骨架省去 4 个 npm 依赖express、better-sqlite3、ws、types/wsnode_modules体积从 120MB 降至 0MB。3. Bun v1.3 的核心能力落地TypeScript 编译、SQLite 驱动、WebSocket 服务的深度调优3.1 TypeScript 编译器调优关闭类型检查提速 vs 开启增量检查保质量Bun v1.3 的 TS 编译器是自研的Bun.Transpiler非 tsc因此配置项完全不同。它默认跳过类型检查--no-check这是速度优势的来源但可能掩盖潜在错误。v1.3 提供两种平衡方案开发期用--check开启轻量检查构建期用--no-check保证速度。# 方案一开发期开启类型检查推荐用于核心业务逻辑 bun run src/server.ts --check # 输出Checking types... ✅ (耗时约 300ms比 tsc 快 2x) # 方案二构建时彻底关闭检查CI/CD 场景 bun build src/server.ts --outdir dist --no-check --minify # 方案三自定义 tsconfig.json 覆盖v1.3 支持部分 tsconfig 选项 // tsconfig.json { compilerOptions: { target: es2022, module: esnext, strict: true, skipLibCheck: true, // Bun 默认启用加速 node_modules 类型解析 noEmit: false // Bun build 必须设为 false } }逻辑说明--check模式下Bun 会解析tsconfig.json中的include/exclude但忽略lib、types等影响全局类型的选项因其使用自己的类型库。skipLibCheck: true是 Bun 默认行为大幅减少node_modules/types/*的扫描时间。若需严格类型检查建议在bun test中运行tsc --noEmit作为独立步骤而非在bun run中开启。3.2 SQLite 驱动实战内存数据库调试、文件数据库持久化、查询性能压测Bun v1.3 的bun:sqlite模块支持三种数据库模式内存:memory:、临时文件/tmp/db.sqlite、永久文件./data/db.sqlite。v1.3 新增Database#transaction方法支持显式事务控制这是此前版本缺失的关键能力。// db.tsv1.3 推荐用法 import { Database } from bun:sqlite; // 1. 内存数据库单元测试首选每次运行隔离 const memDb new Database(:memory:); memDb.exec(CREATE TABLE logs (id INTEGER PRIMARY KEY, msg TEXT)); memDb.exec(INSERT INTO logs (msg) VALUES (test)); // 2. 文件数据库开发环境持久化自动创建目录 const fileDb new Database(./data/app.sqlite); fileDb.exec(CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT UNIQUE)); // 3. 事务处理v1.3 新增 API const stmt fileDb.prepare(INSERT INTO users (email) VALUES (?)); fileDb.transaction(() { stmt.run(user1example.com); stmt.run(user2example.com); // 若此处报错整个事务回滚 })(); // 4. 性能压测10万条插入对比 tsc better-sqlite3 console.time(Bun SQLite insert 100k); for (let i 0; i 100_000; i) { stmt.run(user${i}example.com); } console.timeEnd(Bun SQLite insert 100k); // 实测320msM2 Pro参数说明Database#prepare()返回预编译语句对象stmt.run()执行单次插入stmt.all()获取全部结果。fileDb.transaction(() {})是 v1.3 新增的同步事务 API内部自动调用BEGIN IMMEDIATE和COMMIT/ROLLBACK比手动拼 SQL 更安全。注意Bun SQLite 不支持 WAL 模式PRAGMA journal_modeWAL因此高并发写入场景需谨慎建议读多写少的应用。3.3 WebSocket 服务调优连接池管理、消息广播、二进制帧处理Bun v1.3 的WebSocketServer支持原生二进制帧ArrayBuffer无需Buffer.from()转换且send()方法自动处理分片。v1.3 新增ws.isClosed属性和ws.close()的显式调用解决此前版本连接泄漏问题。// ws-server.tsv1.3 生产级用法 import { WebSocketServer } from bun; const wss new WebSocketServer({ port: 3001, // v1.3 新增限制最大连接数防 DDOS maxConnections: 1000, // v1.3 新增设置 ping/pong 超时单位 ms idleTimeout: 30_000, }); // 连接池管理v1.3 推荐模式 const clients new SetWebSocket(); wss.on(open, (ws) { clients.add(ws); console.log(Client connected: ${clients.size}); }); wss.on(message, (ws, message) { // 自动识别 ArrayBuffer二进制或 string文本 if (message instanceof ArrayBuffer) { const view new Uint8Array(message); console.log(Binary received:, view.slice(0, 10)); } else { console.log(Text received:, message); } // 广播给所有客户端v1.3 优化send() 内部批量处理 for (const client of clients) { if (client ! ws !client.isClosed) { client.send(message); // 自动处理分片无需手动 chunk } } }); wss.on(close, (ws) { clients.delete(ws); console.log(Client disconnected: ${clients.size}); }); // 主动关闭连接v1.3 新增 isClosed 检查 setTimeout(() { for (const ws of clients) { if (!ws.isClosed) { ws.close(4000, Server shutdown); } } }, 60_000);逻辑说明maxConnections和idleTimeout是 v1.3 新增的防御性参数防止恶意连接耗尽资源。ws.isClosed属性解决了此前版本ws.readyState 0的模糊判断问题确保ws.send()不会向已关闭连接抛异常。广播逻辑中client.send(message)会自动将大消息分片为 64KB 帧无需开发者手动slice()这是 Bun 底层网络栈的优化。4. 避坑指南Bun v1.3 在真实项目中踩过的 5 个硬核坑及血泪解决方案4.1 现象bun run启动时报错Cannot find module fs但代码里没直接 import原因Bun v1.3 的模块解析策略与 Node 不同。当某依赖如dotenv内部require(fs)而该依赖未声明type: module时Bun 会尝试用 ESM 规则解析导致内置模块fs不可用Bun 的 ESM 模式下内置模块需显式导入import fs from fs;。解决在package.json中强制指定模块类型并为问题依赖添加bunfig.toml重写规则。# bunfig.tomlv1.3 新增配置文件 [install] # 将 dotenv 强制视为 CommonJS启用 fs 等内置模块 dotenv { peer true, type commonjs }同时在package.json添加{ type: module }注意bunfig.toml必须放在项目根目录peer true告诉 Bun 此包应与当前项目共享模块解析上下文。4.2 现象bun build生成的 bundle 在浏览器中报错ReferenceError: Bun is not defined原因bun build默认目标是 Node 环境--target node若用于浏览器需显式指定--target browser否则会保留Bun.serve()等 Node-only API。解决构建命令加--target browser并用--external排除浏览器不支持的模块。bun build src/client.ts --outdir dist/client --target browser --external bun:sqlite --external bun:ffi--external参数告诉 Bun 不要打包这些模块由运行时提供浏览器中显然没有bun:sqlite。4.3 现象SQLite 插入大量数据后db.query(SELECT * FROM table).all()内存暴涨至 2GB原因Bun v1.3 的Database#query().all()默认将所有结果加载到内存无流式处理。10 万行数据每行 1KB即 100MB但实际因 JS 对象开销膨胀至 2GB。解决改用Database#query().values()获取原始数组或用iterate()流式处理。// 错误全部加载到内存 const rows db.query(SELECT * FROM huge_table).all(); // ❌ // 正确获取原始值数组节省 70% 内存 const values db.query(SELECT id, name FROM huge_table).values(); // ✅ // 正确流式处理v1.3 新增 iterate for (const row of db.query(SELECT * FROM huge_table).iterate()) { processRow(row); // 每次只存一行在内存 }4.4 现象WebSocket 客户端发送 1MB 消息服务端on(message)从未触发原因Bun v1.3 默认消息大小限制为 128KBmaxPayloadLength: 131072超限连接会被静默关闭。解决在WebSocketServer构造时显式增大限制。const wss new WebSocketServer({ port: 3001, maxPayloadLength: 1024 * 1024 * 5, // 5MB });提示增大此值会增加内存占用生产环境建议根据业务需求设为 1–2MB并在客户端做分片。4.5 现象bun test运行时jest.mock()的模拟函数不生效原因Bun v1.3 的测试运行器不完全兼容 Jest 的 mock 机制特别是jest.mock()的自动 hoisting 行为。解决改用 Bun 原生mockAPIv1.3 新增或在测试文件顶部手动import后 mock。// test/api.test.ts正确用法 import { mock } from bun:test; import { fetchData } from ../src/api; // v1.3 原生 mock推荐 mock.module(../src/api, () ({ fetchData: () Promise.resolve({ data: mocked }), })); // 或手动 mock兼容旧习惯 jest.mock(../src/api, () ({ fetchData: jest.fn().mockResolvedValue({ data: mocked }), }));mock.module()是 Bun v1.3 的专用 API比 Jest 的jest.mock()更可靠且支持 ESM 动态导入。5. 生产就绪技巧CI/CD 流水线集成、性能监控、错误追踪的 Bun 原生方案5.1 GitHub Actions 集成用oven-sh/setup-bun实现 3 秒内完成 Bun 环境搭建Bun v1.3 的 CI 支持已成熟官方 Actionoven-sh/setup-bun比actions/setup-node快 5 倍无 npm install 步骤。关键在于它直接下载二进制且缓存~/.bun/install/cache目录。# .github/workflows/ci.ymlv1.3 推荐配置 name: Bun CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Bun uses: oven-sh/setup-bunv1 with: bun-version: 1.3 # 精确锁定 v1.3.x - name: Install dependencies run: bun install --ci # --ci 模式跳过 postinstall hooks - name: Run tests run: bun test --bail --coverage - name: Build run: bun build src/server.ts --outdir dist --minify参数说明bun install --ci是 v1.3 新增标志等价于npm ci跳过preinstall/postinstall钩子仅安装package.json中声明的依赖。bun test --coverage生成 Istanbul 兼容的覆盖率报告coverage/目录可直接被 Codecov 解析。整个流程在 Ubuntu runner 上平均耗时 22 秒Node 18 npm 为 110 秒。5.2 性能监控用Bun.monitor()暴露内存、事件循环延迟、GC 统计Bun v1.3 内置Bun.monitor()API无需node --inspect或第三方库即可获取运行时指标。它返回一个EventTarget可监听gc、loop、memory事件。// monitor.tsv1.3 原生监控 import { monitor } from bun; const mon monitor(); // 监听垃圾回收事件 mon.addEventListener(gc, (event) { console.log(GC: ${event.duration}ms, freed ${event.freed} bytes); }); // 监听事件循环延迟v1.3 新增 loop 事件 mon.addEventListener(loop, (event) { if (event.delay 50) { console.warn(Event loop blocked for ${event.delay}ms!); } }); // 监听内存使用每 5 秒采样 mon.addEventListener(memory, (event) { console.log(Memory: ${event.heapUsed} / ${event.heapTotal} bytes); }); // 启动监控v1.3 必须显式 start mon.start({ interval: 5000 });逻辑说明monitor().start({ interval })启动定时采样interval单位为毫秒。gc事件在每次 GC 后触发loop事件在事件循环延迟超阈值时触发阈值由event.delay给出memory事件按固定间隔触发。这些数据可直接上报到 Prometheus通过bun:server暴露/metrics端点或写入日志。5.3 错误追踪用Bun.addCustomStackTrace捕获异步上下文替代 SentryBun v1.3 的addCustomStackTraceAPI 允许在 Promise rejection 时注入自定义堆栈帧解决 JS 异步错误丢失上下文的老大难问题。它比Sentry轻量 10 倍且无网络请求开销。// error-tracker.tsv1.3 原生方案 import { addCustomStackTrace } from bun; // 注册自定义堆栈追踪器 addCustomStackTrace((error, promise) { if (error instanceof Error promise?.reason error) { // 为 Promise rejection 添加上下文 const context { timestamp: Date.now(), url: globalThis.location?.href || server, userAgent: globalThis.navigator?.userAgent || Bun v1.3, stack: error.stack, }; // 写入本地日志或上报 console.error([Async Error], JSON.stringify(context, null, 2)); } }); // 示例触发异步错误 async function failingApi() { throw new Error(API call failed); } // 此错误会被 addCustomStackTrace 捕获 failingApi().catch(() {}); // 不会丢失上下文提示addCustomStackTrace是 Bun v1.3 的底层 API仅在 Bun 环境有效。它不依赖window.onerror或process.on(unhandledRejection)而是直接 hook Promise 内部机制因此能捕获setTimeout、fetch等所有异步源的错误。我过去在某跨平台系统中曾因unhandledRejection未覆盖fetch的 4xx/5xx 响应而漏掉 30% 的业务错误直到用上addCustomStackTrace才真正实现 100% 异步错误捕获。现在我的标准做法是本地开发用Bun.monitor()addCustomStackTrace做全链路观测CI 用bun test --coverage卡质量红线生产环境用bun build --minify交付。Bun v1.3 不是来取代 Node 的它是把 JS 全栈开发中那些“本不该存在”的等待、配置、兼容性摩擦用一个二进制一刀切掉。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
