Node/TypeScript动态import配置咨询：为何import('node:fs/promises')报错

核心原因 #

错误的本质是Esbuild的external配置与动态导入的模块标识符不匹配，导致Esbuild未将node:fs/promises标记为外部依赖，反而尝试在打包阶段解析该模块，最终触发运行时解析失败。

具体细节：

• 你动态导入的是带node:前缀的node:fs/promises，但Esbuild的external列表仅配置了fs/promises——这两个属于不同的模块标识符，Esbuild无法识别二者指向同一个Node内置模块。
• Node v21.2.0本身完全支持node:前缀的内置模块动态导入，问题不在Node本身，而在打包工具的配置遗漏。

配置修正步骤 #

1. 更新Esbuild的external配置 #

将node:fs/promises添加到external列表中，确保Esbuild直接将该模块交给Node运行时处理，而非自行解析：

// Esbuild配置示例
{
  platform: 'node',
  external: ["node:fs/promises", "fs/promises", /* 其他外部依赖 */],
  format: 'cjs',
  target: 'es2020'
}

2. 确认TypeScript配置兼容性 #

你的tsconfig.json设置（module: NodeNext、moduleResolution: NodeNext）是合理的，NodeNext模式原生支持node:前缀的模块导入。若你的package.json设置了"type": "module"，无需调整——Node v20+可无缝处理Esbuild输出的CJS格式文件，若有需要可手动指定Esbuild的outExtension为.cjs以明确模块类型。

3. 可选：统一导入标识符（非必须） #

如果不想维护两个标识符的external配置，也可将动态导入改为const fs = await import("fs/promises")，与静态导入格式统一并匹配现有external配置。但node:前缀是Node官方推荐的内置模块导入方式，能清晰区分内置模块与第三方包，建议优先通过修正external配置保留该写法。

额外验证点 #

运行打包后的代码前，确认：

• Node版本确实为v21.2.0（确保支持node:前缀的动态导入）
• Esbuild输出的CJS文件中，动态导入语句完整保留了node:fs/promises，未被转义或修改

内容的提问来源于stack exchange，提问作者jonas