如何用ESBuild为Node.js生成单文件ESM格式代码包？

问题分析 #

你遇到的核心矛盾是：设置format: 'esm'但输出仍带有CommonJS特性，切换platform: 'neutral'又触发Node内置模块报错。本质是ESBuild在Node平台下的ESM处理逻辑，以及Node.js对ESM文件的识别规则导致的。

具体解决方案 #

• 强制输出ESM文件后缀
  Node.js默认将.js文件视为CommonJS模块（除非项目根目录package.json设置"type": "module"）。打包单文件时，直接将输出文件后缀改为.mjs是最直接的方式，确保Node.js识别为ESM。修改outfile的后缀，比如把dist/server.js改成dist/server.mjs。

• 优化ESBuild配置参数
  添加两个关键参数，让ESBuild更倾向于处理ESM依赖，减少CommonJS转译干扰：

  • mainFields: ['module', 'main']：优先读取依赖包的ESM入口文件，而非CommonJS入口
  • resolveExtensions: ['.mjs', '.js', '.json']：明确ESM文件的解析顺序
    修改后的配置代码如下：

  export function getESBuildConfig() {
      return {
          format: 'esm',
          sourcemap: true,
          entryPoints: [MAIN_SERVER],
          bundle: true,
          platform: 'node',
          external: [
              'pino',
              'pino-pretty',
              /* 其他外部可用模块 */
          ],
          outfile: './dist/server.mjs', // 改为.mjs后缀
          color: true,
          mainFields: ['module', 'main'],
          resolveExtensions: ['.mjs', '.js', '.json'],
          plugins: [],
      };
  }
  

• 保留platform: 'node'
  不要切换到platform: 'neutral'，这个模式是为跨浏览器和Node的通用场景设计的，不会自动处理Node.js内置模块（如fs、vm）。保持platform: 'node'，ESBuild会自动识别内置模块并保留原生导入语句，不会尝试打包这些模块，避免报错。

• 验证结果
  打包完成后，打开输出的.mjs文件，检查代码是否使用import而非require语句，确认输出为标准ESM格式。

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