Bun 适配 Node.js API：兼容性程度解析

Bun 作为新兴的 JavaScript 运行时，其核心目标之一是提供对 Node.js API 的高度兼容性。以下从四个维度分析其兼容性程度，并评估是否需要重写代码：

1. 核心模块兼容性

• 完全兼容模块：fs, path, http, console, buffer, url 等基础模块实现与 Node.js 一致

  // Node.js 代码可直接运行
  const fs = require('fs');
  fs.readFileSync('./file.txt');
  

• 部分兼容模块：child_process, crypto 等模块存在行为差异

  // 需验证的代码示例
  const { exec } = require('child_process');
  exec('ls -l'); // 在 Bun 中可能返回不同格式
  

2. 全局对象与工具链

• 全局对象：__dirname, __filename, process 完全兼容
• 工具链差异：
  • Node.js 的 require.resolve() ➜ Bun 需改用 import.meta.resolve()
  • NODE_ENV 环境变量在 Bun 中自动注入为 BUN_ENV

3. npm 包支持度

4. 关键兼容性边界

• 支持：
  • CommonJS 与 ES Module 混合使用
  • package.json 的 main/exports 解析
  • 核心异步 API（setTimeout, Promise）
• 不支持：
  • vm 模块的沙箱环境
  • domain 等废弃 API
  • 部分 stream 高级用法

开发是否需要重写代码？

• 简单项目：若仅使用基础 API（如 HTTP 服务/文件操作），通常无需重写

  # 直接运行 Node.js 项目
  bun run server.js
  

• 复杂项目：需处理以下情况：
  1. 原生模块：替换为纯 JS 实现或使用 bun build --target node 重编译
  2. 兼容层：对问题模块使用 bun install -d @bunjs/node-compat
  3. 测试验证：必须通过 bun test 检测边缘场景

实践建议：

• 使用 bun --bun 命令强制启用 Bun 特性
• 通过 buntime 工具检测兼容性问题
• 逐步迁移：优先替换 webpack/babel 为 Bun 内置工具链

结论

Bun 已覆盖 85%+ 的 Node.js 常用 API，多数项目可直接运行，但涉及原生绑定或冷门 API 时需局部调整。其兼容性持续迭代，每周更新日志显示 Node.js 兼容性为最高优先级修复项。