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

2023-10-30


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

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

esbuild简单介绍

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

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

路径解析配置项 Path resolution

外部模块 External

Supported by: Build

您可以将文件或包标记为外部,可以将它们从build中排除。导入语句将被保留(对iifecjs格式使用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的文件或模块。它允许您指定浏览器的备用入口点。请注意,包可以同时使用browsermodule字段(请参阅下面的注释)。

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

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

对于包的开发者

如果您想编写一个将browser字段与module字段结合使用的包,那么您可能需要填写完整的CommonJS-vs-ESMbrowser-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的变体。如果你省略了这四个条目中的一个,那么你就有可能选择到错误的变体。例如,如果您省略了CommonJSbrowser构建的条目,那么就可能选择到CommonJSnode构建。

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

结语

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

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

(本文完)

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

本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)

esbuild中文文档-路径解析配置项(Path resolution - External、Main fields) 的相关文章

随机推荐