esbuild中文文档-API概述（Overview)

最新推荐文章于 2024-05-03 10:00:00 发布

励志前端小黑哥

最新推荐文章于 2024-05-03 10:00:00 发布

阅读量192

点赞数

分类专栏： esbuild中文文档文章标签：软件构建 javascript go transformer

本文链接：https://blog.csdn.net/qq_21197033/article/details/132806804

版权

esbuild中文文档专栏收录该内容

21 篇文章 2 订阅

订阅专栏

文章目录

API概述 Overview

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

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

欢迎大家点赞收藏我的专栏：esbuild中文文档专栏，专栏内容完全免费，收藏以备不时之需

API概述 Overview

最常用的两个esbuild API是build和transform。本文对每个选项进行了高层次的描述，随后会为每个单独的API选项提供文档。

Build

这是esbuild的主要接口。通常会传递一个或多个入口点文件和各种选项进行处理，然后esbuild将结果写回文件系统。下面是一个简单的示例，它支持与输出目录绑定：

esbuild app.ts--bundle--outdir=dist

build API的高级使用涉及设置长时间运行的构建上下文。此上下文在JS和Go中是一个显式对象，但在CLI中是隐式的。使用给定上下文完成的所有构建都共享相同的构建选项，并且后续构建是增量完成的（即，它们重用以前构建的一些worker以提高性能）。这对开发很有用，因为esbuild可以在您工作时在后台为您重新构建应用程序。

有三种不同形式的增量构建API：

监视模式（Watch mode）告诉esbuild监视文件系统，并在您编辑和保存可能使生成无效的文件时自动为您重新生成。以下是一个示例：

esbuild app.ts --bundle --outdir=dist --watch
[watch] build finished, watching for changes...

服务模式（Serve mode）会启动一个本地开发服务器，该服务器提供最新构建的结果。传入的请求会自动启动新的构建，因此当您在浏览器中重新加载页面时，您的web应用程序始终是最新的。以下是一个示例：

esbuild app.ts --bundle --outdir=dist --serve

 > Local:   http://127.0.0.1:8000/
 > Network: http://192.168.0.1:8000/

127.0.0.1:61302 - "GET /" 200 [1ms]

重构建模式（rebuild mode）允许你可以手动调用构建。这在将esbuild与其他工具集成时非常有用（例如，使用自定义文件观察程序或开发服务器，而不是esbuild的内置服务器）。以下是一个示例：

let ctx = await esbuild.context({
  entryPoints: ['app.ts'],
  bundle: true,
  outdir: 'dist',
})

for (let i = 0; i < 5; i++) {
  let result = await ctx.rebuild()
}

这三个增量构建API可以组合在一起。要启用实时重新加载（在编辑和保存文件时自动重新加载页面），您需要在同一上下文中启用监视和服务。

处理完上下文对象后，可以在上下文上调用dispose（）以等待现有构建完成，停止监视和/或服务模式，并释放资源。

Transform

Transform API能在不访问文件系统的情况下对单个字符串进行操作。这使得它非常适合在没有文件系统（如浏览器）或作为其他工具链的一部分。下面是一个简单的变换：

echo 'let x: number = 1' | esbuild --loader=ts
# let x = 1;

对于某些场景来说，使用字符串而不是文件作为输入更符合人们感官。文件系统隔离有一定的优点（例如，在浏览器中工作，不受附近package.json文件的影响），也有一定的缺点（例如，不能与bundling或插件一起使用）。如果您的场景不适合Transform API，那么您应该使用更通用的Build API。

JS API的特殊细节（JS-specific details）

适用于esbuild的JS API有异步和同步两种风格。推荐使用异步API，因为它适用于所有环境，而且速度更快、功能更强大。同步API只在Nodejs中工作，并且只能做某些事情，但有时在特定的情况下是必要的。详细说明：

异步API（Async API）

异步API使用promise作为返回结果。请注意，由于使用了import和顶级await关键字，您可能不得不在node中使用.mjs文件扩展名：

import * as esbuild from 'esbuild'

let result1 = await esbuild.transform(code, options)
let result2 = await esbuild.build(options)

优点：

您可以使用带有异步API的插件
当前线程未被阻止，因此您可以在此期间执行其他工作
您可以同时运行多个esbuild API，然后将这些调用分布在所有可用的CPU中，以获得最大性能

缺点：

使用promise可能会导致代码更加混乱，尤其是在CommonJS中，顶级await不可用
在必须同步的情况下不起作用，例如在require.extensions中

同步API（Sync API）

同步API的调用是直接在行内就返回结果了：

let esbuild = require('esbuild')

let result1 = esbuild.transformSync(code, options)
let result2 = esbuild.buildSync(options)

优点：

避免promise可能会有更干净的代码，尤其是在顶级await不可用的情况下
在必须同步的情况下工作，例如在require.extensions中

缺点：

您不能将插件与同步API一起使用，因为插件是异步的
它会阻塞当前线程，因此在此期间无法执行其他工作
使用同步API会阻止esbuild并行调用

在浏览器中使用（In the browser）

esbuild API也可以使用Web Worker中的WebAssembly在浏览器中运行。要利用这一点，您需要安装esbuild-wasm包，而不是esbuild包：

npm install esbuild-wasm

浏览器API类似于Node的API，只是您需要首先调用initialize()，并且需要传递WebAssembly二进制文件的URL。API的同步版本也不可用。假设你使用的是bundler，它看起来是这样的：

import * as esbuild from 'esbuild-wasm'

await esbuild.initialize({
  wasmURL: './node_modules/esbuild-wasm/esbuild.wasm',
})

let result1 = await esbuild.transform(code, options)
let result2 = esbuild.build(options)

如果您已经从worker运行此代码，并且不希望initialize创建另一个工作线程，则可以将worker:false传递给它。然后它将在与调用initialize的线程相同的线程中创建WebAssembly模块。

您还可以在HTML文件中的script标签中使用esbuild的API，而无需通过加载带有＜script＞标记的lib/browser.min.js文件来使用打包工具。在这种情况下，API创建了一个名为esbuild的全局变量，该全局变量保存了API对象：

<script src="./node_modules/esbuild-wasm/lib/browser.min.js"></script>
<script>
  esbuild.initialize({
    wasmURL: './node_modules/esbuild-wasm/esbuild.wasm',
  }).then(() => {
    ...
  })
</script>

如果要将此API与ECMAScript模块一起使用，则你应该导入esm/browser.min.js文件：

<script type="module">
  import * as esbuild from './node_modules/esbuild-wasm/esm/browser.min.js'

  await esbuild.initialize({
    wasmURL: './node_modules/esbuild-wasm/esbuild.wasm',
  })

  // ...
</script>