Bun 中 fs 与 node:fs 导入方式详解：兼容性、语义与最佳实践-js教程-PHP中文网

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

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

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

在 Bun 中迁移 Node.js 项目时，关于核心模块（如 fs、path、http、crypto）的导入方式，开发者常面临一个看似微小却影响长期可维护性的选择：是继续沿用传统写法 import fs from 'fs'，还是转向显式协议写法 import fs from 'node:fs'？

答案很明确：两者功能等价、运行时表现一致，但 node:fs 是更优的工程实践选择。

✅ 兼容性与行为完全一致

Bun 内置了完整的 Node.js 兼容层，其 fs 模块实现与 Node.js 高度对齐。无论你写：

import fs from 'fs';           // ✅ 完全支持
import fs from 'node:fs';      // ✅ 同样支持，语义更清晰

二者在 Bun（及 Node.js）中均指向同一模块实例。你可以通过简单验证确认：

Rydberg Agent Node

使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r

下载

// test-imports.ts
import fs1 from 'fs';
import fs2 from 'node:fs';

console.log(fs1 === fs2); // true —— 是同一个对象

这说明 Bun 并未做“双份加载”，也不存在额外解析开销或内存冗余，性能零差异。

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

语义明确，提升可读性
node: 协议是 Node.js 官方自 v14.18.0 起正式推广的规范（RFC #47），用于显式标识“这是 Node.js 内置模块”，而非第三方包或相对路径文件。在大型项目或团队协作中，node:fs 能立即消除歧义，避免与同名 npm 包（如 fs-extra 或历史遗留的 fs polyfill）产生混淆。
强化跨运行时一致性
Deno 和 Bun 均原生支持 node: 协议，而部分新兴工具链（如某些 bundler 的严格模式）可能默认禁用裸导入（bare imports）以提升确定性。采用 node:fs 可让你的代码天然具备更好的跨平台适应性，降低未来迁移到 Deno 或混合环境时的适配成本。
符合 Bun 生态演进方向
尽管 Bun 当前对 'fs' 的支持非常稳健，但其底层模块解析器正持续向更严格的 Node.js ESM 规范对齐。官方文档与 CLI 提示（如 bun run --check）已倾向鼓励 node: 前缀。使用它，即是主动拥抱 Bun 的“渐进式现代化”哲学——不强制重构，但引导最佳实践。

⚠️ 注意事项与迁移建议

无需全局替换，但建议新代码统一采用：已有 import fs from 'fs' 的代码可保留；新增模块导入、重构文件或编写测试时，请默认使用 node:fs。
配套更新其他模块：同理适用于 node:path、node:http、node:https、node:stream、node:util 等所有 Node.js 核心模块。

避免混用造成风格割裂：同一项目中不建议部分文件用 fs、部分用 node:fs，应通过 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."
      }
    ]
  }
}