Bun中fs与node:fs导入详解：兼容性、语义及最佳实践

Bun 完全兼容 Node.js 的模块导入语法，import fs from 'fs' 和 import fs from 'node:fs' 均可正常工作且性能无差异；推荐优先使用 node:fs 等显式协议导入，以增强代码可读性、明确模块来源，并为未来生态演进预留兼容性保障。

从 Node.js 迁移到 Bun 时，许多开发者会为良好的兼容性感到轻松。然而，在这个“无缝切换”的舒适区里，一个看似微小的细节——如何导入 fs 这类核心模块——其实影响着项目的长期健康度。

是继续使用熟悉的 import fs from 'fs'，还是换成带前缀的 import fs from 'node:fs'？

结论明确：两者在功能、性能上完全等价，但后者是更值得推荐的工程实践。 这并非技术优劣问题，而是关于代码清晰度和未来适应性的风格选择。

兼容性与行为完全一致

首先可以放心，Bun 对这两种写法均提供原生支持。无论使用哪种方式导入，最终拿到的都是同一个模块对象，没有双份加载，也没有额外性能开销。

一个简单验证就能说明问题：

// test-imports.ts
import fs1 from 'fs';
import fs2 from 'node:fs';
console.log(fs1 === fs2); // true —— 是同一个对象

因此，在运行时层面，选择哪个都一样。真正的区别在于代码的“表达力”和“意图”。

为什么推荐 node:fs？三大理由

既然没有区别，为什么要多打几个字符？这背后有三个实际理由。

1. 语义明确，提升可读性

node: 前缀协议是 Node.js 官方从 v14.18.0 开始正式推广的规范。其核心价值在于“显式声明”——明确告诉读代码的人，这个 fs 是 Node.js 平台的内置模块，而不是某个同名的第三方 npm 包（如 fs-extra），也不是本地文件。

在大型项目或团队协作中，这种“自文档化”特性非常宝贵，能立即消除潜在的歧义。

2. 强化跨运行时一致性

当前 Ja vaScript 生态不再是 Node.js 一家独大。Deno 原生支持 node: 协议，Bun 也原生支持。更重要的是，一些新兴工具链和打包器为追求确定性和安全性，开始倾向于限制或禁用裸导入（即不带协议的 'fs'）。

提前采用 node:fs，相当于为代码增加了一层跨平台、跨运行时的“兼容性保险”，未来需要迁移或集成时阻力更小。

3. 符合生态演进方向

观察 Bun 官方文档和工具链提示（如 bun run --check），其生态正朝着更规范、更明确的 Node.js ESM 标准对齐。鼓励使用 node: 前缀，正是这种“渐进式现代化”思路的体现——不破坏现有兼容性，但引导开发者走向最佳实践。

跟随主流工具链的推荐方向，往往能让项目在未来的升级和维护中更加顺畅。

注意事项与迁移建议

道理已明，具体该如何操作？这里有几个务实建议。

无需大动干戈地全局替换。存量代码保持原样运行完全没问题。建议将新编写的代码、重构的模块或测试文件作为实践新规范的起点，统一使用 node:fs。

别忘了其他核心模块。同样的逻辑适用于 node:path、node:http、node:stream、node:util 等所有 Node.js 内置模块。保持风格统一是关键。

用工具约束风格，避免割裂。最忌项目内两种写法混用。可通过配置 ESLint 规则保证一致性，例如使用 @typescript-eslint/no-restricted-imports 规则：

{
  “rules”: {
    “@typescript-eslint/no-restricted-imports”: [
      “error”,
      {
        “patterns”: [“^fs$”, “^path$”, “^http$”],
        “message”: “Use 'node:fs', 'node:path', 'node:http' instead for clarity and future compatibility.”
      }
    ]
  }
}

总结：选 node:fs，不是妥协，而是远见

选择 node:fs 并非技术上的必选项，而是工程素养的体现。它不增加任何运行时成本，却能显著提升代码清晰度、团队协作效率以及项目面对未来生态变化的韧性。

在追求“快”的 Bun 生态里，这个小小的前缀恰恰体现了“快而不糙，新而兼容”的专业态度——速度要追求，代码的长期可维护性和清晰度同样不能妥协。