Bun 实战：将现有 Node.js 项目迁移到 Bun，避坑指南

Bun 实战：Node.js 项目迁移到 Bun 避坑指南

Bun 作为新一代 JavaScript 运行时，兼容 Node.js 生态但性能更优。以下是迁移关键步骤与避坑要点：

---

一、迁移准备

1. 环境检查

   • 安装 Bun：curl -fsSL https://bun.sh/install | bash
   • 验证版本：bun --version
   • 检查依赖兼容性：

     bun install  # 自动替换 npm/yarn
     

2. 备份与隔离

   • 备份 package.json 和 node_modules
   • 新建分支：git checkout -b bun-migration

---

二、迁移核心步骤

graph LR
A[替换启动命令] --> B[适配模块系统]
B --> C[处理原生模块]
C --> D[测试运行]

1. 启动命令迁移

   • 替换 npm run start → bun run start
   • 优化脚本（示例）：

     // package.json
     "scripts": {
       "start": "bun run index.js",  // 显式指定 Bun
       "dev": "bun --hot server.js"  // 启用热重载
     }
     

2. 模块系统适配

   • CommonJS 问题：Bun 默认支持 ESM，若需强制 CJS：

     // 文件首行添加
     module.exports = {}; 
     

   • 混合导入避坑：避免 .cjs/.mjs 混用，统一扩展名为 .js。

3. 原生模块处理

   • Node-API 模块（如 bcrypt）：

     bun add bcrypt  # 尝试 Bun 兼容版本
     

   • 不兼容模块：
     • 方案 1：替换为纯 JS 实现（如 bcryptjs）
     • 方案 2：通过 bun build 编译为可执行文件

---

三、高频踩坑点与解决方案

问题类型	现象	解决方案
全局变量差异	process.browser 未定义	改用 typeof Bun !== 'undefined'
路径解析错误	__dirname 报错	使用 import.meta.dir
环境变量加载	.env 文件未生效	显式加载：Bun.env
TS 类型冲突	类型检查失败	删除 @types/node 依赖

---

四、验证与优化

1. 运行测试

   bun test  # 替代 jest/mocha
   

2. 性能调优

   • 启用 Bun 的 JSC 引擎：

     bun --js-engine=jsc start.js
     

   • 检查内存占用：bun --smol（轻量模式）

3. 部署注意事项

   • Dockerfile 示例：

     FROM oven/bun:1.0
     COPY . .
     RUN bun install --production
     CMD ["bun", "start"]
     

---

五、回滚预案

若迁移失败：

1. 还原 package.json 和锁文件
2. 重装 Node 依赖：

   rm -rf node_modules
   npm install  # 或 yarn
   

提示：Bun 仍在快速迭代，关注 GitHub Issues 获取最新兼容性动态。优先迁移工具链（测试/打包），再逐步迁移核心业务代码。