如何在项目中平滑迁移到 Bun 2.0

最近在技术圈里，大家都在聊把老项目搬到 Bun 2.0 的事儿。听说有团队把原本要熬夜调试的部署脚本，直接换成了几行 Bun 命令，速度直接提了好几倍。咱们不妨把这事儿拆开来看，看看怎么才能不踩坑、顺畅切换。

迁移前的准备

搬家前，先把现有的依赖清单掏出来，别等到 Bun 报错才发现某个 C++ 插件根本不兼容。可以用 npm ls --depth=0 或 pnpm list 把表面依赖列个清楚，再对照 Bun 官方的兼容列表，挑出几颗“疑难杂症”。

• 把项目根目录的 package.json 里的 scripts 复制一份，留作回滚。
• 检查是否使用了 node-gyp 编译的原生模块，最好先在本地跑一遍 bun install 看看是否能自动编译。
• 把 TypeScript 配置文件 tsconfig.json 简化，Bun 自带的编译器对一些高级选项支持不完整。

一步步切换运行时

准备完毕后，直接装 Bun：curl -fsSL https://bun.sh/install | bash。安装完毕，先把 npm run dev 改成 bun run dev，别忘了把 node_modules 删掉，让 Bun 重新拉取依赖。这样做的好处是，Bun 会把依赖写进更轻量的 bun.lockb，后续安装几乎是瞬间完成。

# 原来的启动脚本
npm run dev

# 换成 Bun
bun run dev

# 安装依赖
bun install

改完脚本后，跑一遍单元测试。Bun 自带的测试 runner 与 Jest API 兼容，只要把 jest 的命令改成 bun test，大多数测试都能直接复用。遇到不兼容的测试文件，先把它们标记为 “skip”，等后面再逐个修复。

常见坑与应对

• 原生模块编译失败时，先查官方是否提供了对应的 bun:ffi 替代方案。
• 环境变量写法有细微差别，尤其是 Windows 下的路径分隔符，建议统一使用 path.join。
• 如果项目里用了 dotenv 加载 .env 文件，记得在 bunfig.toml 中把 env = true 打开。

把这些细节都踩平后，整个项目的启动时间从原来的 3 秒左右，直接压到不到 1 秒，连 CI 里跑测试的时间都省了不少。搬家不是一蹴而就的事，但只要按部就班、先保留一套回滚方案，基本上能让大家在不慌不忙的状态下，悄悄把旧环境换成 Bun 2.0。