如何配置esbuild转换node_modules中的依赖代码？

开发者阿泽

2026-6-22

问题：esbuild无法转换node_modules依赖中的解构语法

我在Ruby on Rails项目中用esbuild构建JS应用，开发环境的构建命令如下：

esbuild app/javascript/*.* --bundle --target=es2018 --sourcemap --define:global=window --loader:.png=file --loader:.eot=dataurl --loader:.woff=dataurl --loader:.woff2=dataurl --loader:.ttf=dataurl --loader:.svg=dataurl --public-path=/asssets --asset-names=[name]-[hash].digested --outdir=app/assets/builds/

我依赖--target=es2018参数，希望把较新的JS语法转成ES6/7代码，但构建产物里仍有大量来自node_modules依赖的对象/数组解构语法。

我尝试过手动禁用解构特性：

esbuild app/javascript/*.* --bundle --target=es2018 --supported:destructuring=false ...

但出现报错：

Transforming destructuring to the configured target environment
("es2018" + 1 override) is not supported yet

而且这个报错只出现在我自己的项目代码中，我自己代码里的解构语法其实已经被正确转换了。

解决方案

强制esbuild处理node_modules依赖：esbuild默认会跳过node_modules里的文件转换，毕竟多数第三方包都会自己编译到兼容版本。如果你的依赖没做兼容编译，就得让esbuild主动处理它们。可以在构建命令里加--packages=bundle（代替默认的--packages=external），或者用配置文件时设置packages: 'bundle'，同时加上--ignore-annotations忽略依赖里的编译提示注释，确保按你的target要求转换。
别碰--supported配置：你遇到的报错是因为esbuild现在还做不到把解构语法降级到es2018以下的环境。手动设--supported:destructuring=false相当于要求把解构转成比es2018更老的语法，这超出了它的能力范围。另外你说自己的项目代码解构被正确转换，其实是误解——es2018本身就支持解构，所以--target=es2018根本不会触发解构的转换，你看到的变化可能是其他配置导致的。
调整target版本：如果你的实际目标环境是不支持解构的（比如ES5/ES6早期版本），直接把--target改成更低的版本，比如--target=es2015。这时候esbuild会自动把解构这类新语法转成兼容代码，当然也要记得开启对node_modules的转换。不过要注意，esbuild对某些ES6+特性的降级支持有限，部分复杂语法可能无法完全转成低版本代码。
改用配置文件管理：命令行参数太多容易乱，换成esbuild.config.js更灵活，示例配置如下：

require('esbuild').build({
  entryPoints: ['app/javascript/*.*'],
  bundle: true,
  target: 'es2018', // 或者根据实际需求改成es2015
  sourcemap: true,
  define: { global: 'window' },
  loader: {
    '.png': 'file',
    '.eot': 'dataurl',
    '.woff': 'dataurl',
    '.woff2': 'dataurl',
    '.ttf': 'dataurl',
    '.svg': 'dataurl',
  },
  publicPath: '/assets',
  assetNames: '[name]-[hash].digested',
  outdir: 'app/assets/builds/',
  // 强制打包并转换node_modules里的依赖
  packages: 'bundle',
  // 忽略依赖中的编译注释，强制按target转换
  ignoreAnnotations: true,
}).catch(() => process.exit(1))

之后用node esbuild.config.js执行构建就行。

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

如何配置esbuild转换node_modules中的依赖代码？

解决方案 #

解决方案