esbuild中文文档-输出内容配置项（Output contents - Format、Global name、Legal comments、Line limit、Splitting）

哈喽，大家好！我是「励志前端小黑哥」，我带着最新发布的文章又来了！

老规矩，小手动起来~点赞关注不迷路！

esbuild简单介绍

esbuild为了突破了JavaScript语言的瓶颈，采用了Go语言编写，构建速度与同代码量下的webpack对比提升在10倍以上，开创了构建工具性能的新时代。

它的中文文档，本人正在不断的更新完善中，欢迎大家关注阅读！

Output contents配置项

输出格式 Format

Supported by: Transform | Build

这个配置项可以设置生成的JavaScript文件的输出格式。目前有三个可能的值可以配置：iife、cjs和esm。当未指定输出格式时，如果启用了打包，esbuild将为您自动选择合适的输出格式（按下面这几种方式），如果禁用了打包，则esbuild不执行任何格式转换。

iife

iife格式表示“立即执行的函数表达式”，更倾向于在浏览器中运行的代码。将代码包裹在函数表达式中可以确保代码中的任何变量不会意外地与全局范围中的变量冲突。如果入口文件需要在浏览器中暴露全局变量，则可以使用全局名称Global name来配置该全局变量的名称。当未指定输出格式、启用打包并且platform设置为browser（默认情况下为浏览器）时，iife格式将自动启用。指定iife时生成的格式如下所示：

$ echo 'alert("test")' | esbuild --format=iife
(() => {
  alert("test");
})();

CommonJS

cjs格式代表CommonJS，更加倾向于在Node中运行的代码。它假定环境包含exports、require和module。ECMAScript模块语法中具有导出的入口文件将被转换为一个模块，这个模块的每个导出exports上都将生成一个getter函数。当未指定输出格式、打包是启动的，并且platform设置为node时，cjs格式将自动启用。指定cjs格式如下所示：

$ echo 'export default "test"' | esbuild --format=cjs
...
var stdin_exports = {};
__export(stdin_exports, {
  default: () => stdin_default
});
module.exports = __toCommonJS(stdin_exports);
var stdin_default = "test";

ESM

esm格式代表ECMAScript模块。它假定环境支持导入和导出语法。以CommonJS模块语法导出的入口文件将转换为module.exports，且只有一个default值的导出模块。当未指定输出格式、启用打包且platform设置为neutral时，将自动启用esm格式。指定esm格式如下所示：

$ echo 'module.exports = "test"' | esbuild --format=esm
...
var require_stdin = __commonJS({
  "<stdin>"(exports, module) {
    module.exports = "test";
  }
});
export default require_stdin();

esm格式既可以在浏览器中使用，也可以在node中使用，但必须将其作为模块显式加载。如果从另一个模块导入，则会自动将其视为模块加载。否则：

• 在浏览器中，可以使用<script src="file.js" type="module"></script>来加载esm模块。

• 在node中，您可以使用node --experimental-modules file.mjs来加载esm模块。请注意，除非您在package.json文件中配置了"type"："module"，否则node需要.mjs扩展名才能加载esm模块。可以使用esbuild中的输出扩展名out extension配置项来自定义esbuild生成文件的扩展名。您可以在此处阅读有关在node中使用ECMAScript模块的更多信息。

全局变量名 Global name

Supported by: Build and Transform

只有当format设置为iife（立即调用的函数表达式）时，此配置项才会生效。它设置全局变量的名称，用于存储入口点的导出：

echo 'module.exports = "test"' | esbuild --format=iife --global-name=xyz

使用iife格式并指定全局变量名后，将生成如下代码：

var xyz = (() => {
  ...
  var require_stdin = __commonJS((exports, module) => {
    module.exports = "test";
  });
  return require_stdin();
})();

全局名称也可以是复合表达式的一个属性，在这种情况下，esbuild将生成具有该属性的一个全局变量。如果全局变量存在冲突是不会被覆盖的。这可以用于实现类似“名称空间”的效果，将多个独立脚本导出添加到同一全局变量上。例如：

echo 'module.exports = "test"' | esbuild --format=iife --global-name='example.versions["1.0"]'

上面使用的复合全局变量名生成的代码如下所示：

var example = example || {};
example.versions = example.versions || {};
example.versions["1.0"] = (() => {
  ...
  var require_stdin = __commonJS((exports, module) => {
    module.exports = "test";
  });
  return require_stdin();
})();

法律意见 Legal comments

Supported by: Build and Transform

“法律意见”被认为是JS中的所有语句级注释或CSS中包含@license或@preserve或以//!、/*!开头的规则注释。默认情况下，这些注释保留在输出文件中，因为这遵循了代码原始作者的意图。但是，可以使用以下选项之一配置此行为：

• none

不要保留任何法律意见。

• inline

保留所有法律意见。

• eof

将所有法律注释移到文件末尾。

• linked

将所有法律注释移到.LEGAL.txt文件中，并用注释链接到它们。

• external

将所有法律注释移动到.LEGAL.txt文件中，但不要链接到它们。

当启用绑定时，默认行为为eof，否则为linked。设置法律意见的代码示例如下所示：

esbuild app.js --legal-comments=eof

请注意，JS的“语句级别”和CSS的“规则级别”意味着注释必须出现在允许多个语句或规则的上下文中，例如在顶级范围、语句中，或规则块中。因此，表达式内部或声明级别的注释不被视为法律意见。

行数限制 Line limit

Supported by: Build and Transform

此配置项可以防止esbuild生成超长行的输出文件，这有助于提升较差的文本编辑器中编辑性能。将其设置为正整数，以告诉esbuild超过某个数值之后立即结束。例如，这会在行字符数超过80后对其后续代码进行拼接压缩处理：

esbuild app.ts --line-limit=80

行字符数在超过限制之后会被截断，因为检查何时超过限制比预测何时将要通过限制更简单，而且在生成输出文件时避免备份和重写内容更快。所以这个极限只是近似的。

此设置适用于JavaScript和CSS，即使在禁用压缩功能时也能正常工作。请注意，启用此设置会使文件变大，因为额外的换行符会占用文件中的额外空间（即使在gzip压缩之后）。

代码拆分 Splitting

Supported by: Build

代码拆分仍在开发过程中。它目前只适用于esm输出格式。在代码分割块之间的导入语句还有一个已知问题。您可以关注the tracking issue以获取有关此功能的更新。

启用“代码拆分”，无非有下面两个目的：

• 多个入口点之间共享的代码被拆分为一个单独的共享文件，两个入口点都导入该文件。这样，如果用户先浏览一个页面，然后再浏览另一个页面时，如果共享部分已经被浏览器下载并缓存，他们就不必从头开始下载第二个页面的所有JavaScript。

• 通过异步import()表达式引用的代码将被拆分到一个单独的文件中，并且只有在计算该表达式时才加载。这可以让你只在启动时下载所需的代码，然后在以后需要时懒加载额外的代码，从而缩短应用程序的初始加载时间。
  如果不启用代码拆分，import()表达式将变为Promise.resolve().then（()=>require()）。这仍然保留了表达式的异步语义，但这意味着导入的代码包含在同一个打包文件中，而不是拆分成一个单独的文件。

启用代码拆分时，还必须使用outdir设置配置输出目录：

esbuild home.ts about.ts --bundle --splitting --outdir=out --format=esm

结语

笔者根据esbuild文档搭建了一套简洁的ts开发脚手架工程，编译速度非常快！脚手架还整合了eslint，另一篇文章还附带了调试教程，需要的朋友看这里：esbuild配合vscode搭建的ts开发环境，这编译速度，真香

另外，esbuild中文文档专栏，本人目前正在翻译整理，关注我，有最新的翻译文档会第一时间通知你！

（本文完）

励志前端小黑哥，全网唯一账号！
关注我，带你了解更多前端知识！