esbuild中文文档-路径解析配置项（Path resolution - External、Main fields）

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

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

esbuild简单介绍

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

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

路径解析配置项 Path resolution

外部模块 External

Supported by: Build

您可以将文件或包标记为外部，可以将它们从build中排除。导入语句将被保留（对iife和cjs格式使用require的导入，对esm格式使用import的导入），而不会被打包，并且这些保留的语句将在运行时进行计算。

这有几个用途。首先，它可以从您的打包中修剪不必要的代码，这些代码是您明确知道的永远不会执行的代码。例如，一个包可能包含某些仅在node中运行的代码，但您只计划在浏览器中使用该程序包。它还可以用于在运行时从无法打包的package中导入node代码。例如，fsevents包包含一个esbuild不支持的本机扩展。将某个东西标记为外部，如下所示：

$ echo 'require("fsevents")' > app.js
$ esbuild app.js --bundle --external:fsevents --platform=node

// app.js
require("fsevents");

您也可以在外部路径中使用*通配符，将所有匹配到的文件标记为外部文件。例如，可以使用*.png删除所有.png文件，也可以使用/images/*删除以/images/开头的所有路径：

esbuild app.js --bundle "--external:*.png" "--external:/images/*"

外部路径在路径解析之前和之后都会应用，这使您可以与源代码中的导入路径和文件系统的绝对路径进行匹配。一个路径在与任意一种情况匹配时，该路径会被视为外部路径。具体行为如下：

• 在开始路径解析之前，将根据所有外部路径检查导入路径。此外，如果外部路径看起来像包路径（即不是以/或./或../开头），则会检查导入路径，以查看它们是否将该包路径作为路径前缀。

这意味着--external:@foo/bar隐含地也意味着--external:@foo/bar/*，它与导入路径@foo/bar/baz匹配。因此，它也将@foo/bar包内的所有路径标记为外部路径。

• 路径解析结束后，将对照所有看起来不像包路径的外部路径（即以/或./或../开头的路径）检查解析的绝对路径。但在检查之前，外部路径将与当前工作目录连接，然后进行规范化，生成绝对路径（即使它包含*通配符）。

这意味着您可以使用--external:./dir/*将目录dir中的所有内容标记为外部模块。请注意，前缀./很重要。如果没有前缀，直接使用--external:dir/*会被视为包路径，在路径解析结束后不会再进行检查。

主字段 Main fields

Supported by: Build

在node中导入包时，该包的package.json文件中的main字段确定了要导入的文件（以及许多其他规则）。包括esbuild在内的大多数JavaScript打包器允许您在解析包时指定额外的package.json字段。通常使用的此类字段至少有三个：

• main

这是要与node一起使用的所有包的标准字段。名称main被硬编码到node的模块解析逻辑中。因为它是用于node的，所以可以明确地预知到该字段中的文件路径是CommonJS风格的模块。

• module

这个字段来自一个关于如何将ECMAScript模块集成到node中的提议。因此，可以明确地预知该字段中的文件路径是ECMAScript样式的模块。这个提议没有被node采用（node使用“type”：“module”），但它已被大多数的bundler采用了，因为ECMAScript风格的模块可以更好地进行树抖动或删除死代码。

对于包作者：有些包错误地将module字段用于浏览器的代码，而将node的代码用于main字段。这可能是因为node忽略了module字段，并且人们通常只对特定于浏览器的代码使用bundler。然而，对于node代码进行打包也很有价值（例如，它减少了下载和启动时间），并且将浏览器的代码放在module中的包阻止了打包器有效地进行树抖动。如果试图在包中发布特定于浏览器的代码，请改用浏览器字段。

• browser

该字段来自一项提案，该提案允许打包器用browser友好的替换基于node的文件或模块。它允许您指定浏览器的备用入口点。请注意，包可以同时使用browser和module字段（请参阅下面的注释）。

默认的main字段取决于当前platform设置。这些默认值是与现有软件包生态系统最广泛兼容的。但是，您也可以自定义：

esbuild app.js --bundle --main-fields=module,main

对于包的开发者

如果您想编写一个将browser字段与module字段结合使用的包，那么您可能需要填写完整的CommonJS-vs-ESM和browser-vs-node矩阵中的所有四个条目。为此，您需要使用browswer字段的扩展形式，它是一个map，而不仅仅是一个字符串：

{
  "main": "./node-cjs.js",
  "module": "./node-esm.js",
  "browser": {
    "./node-cjs.js": "./browser-cjs.js",
    "./node-esm.js": "./browser-esm.js"
  }
}

main字段期望使用CommonJS格式，而module字段期望使用ESM格式。关于使用哪种格式，取决于使用浏览器的变体还是node的变体。如果你省略了这四个条目中的一个，那么你就有可能选择到错误的变体。例如，如果您省略了CommonJS的browser构建的条目，那么就可能选择到CommonJS的node构建。

请注意，使用main、module和browser是执行此操作的旧方法。还有一种新的方法可以做到这一点，你可能更喜欢使用它：package.json中的exports字段。它提供了一组不同的设置方法。例如，它使您能够更精确地控制包中所有子路径的导入（而main字段仅使您能够控制入口点），但它可能会导致包被多次导入，具体取决于您如何配置它。

结语

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

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

（本文完）

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