esbuild中文文档-基础配置项（General options - Serve）

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

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

esbuild简单介绍

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

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

服务模式（Serve）

Supported by: Build

如果你想让你的应用程序在编辑时自动重新加载，你应该阅读实时重载(Live reload)相关的内容。它将服务模式与监视模式相结合，以侦听对文件系统的更改。

服务模式会启动一个web服务器，将您的代码提供给电脑上的浏览器。这里有一个例子，它将src/app.ts绑定到www/js/app.js中，然后还通过http://localhost:8000/提供服务:

esbuild src/app.ts --outdir=www/js --bundle --servedir=www

如果您创建了包含以下内容的www/index.html文件，那么当您访问http://localhost:8000/时，src/app.ts文件中的代码将被加载:

<script src=“js/app.js”></script>

使用esbuild的内置web服务器而不是新启另一个web服务器的一个好处是，无论何时重新加载，esbuild提供的文件都是最新的。其他服务器的开发配置不一定是这样的。一种最常见的配置是运行本地文件监听器，每当输出文件对应的输入文件发生更改时，该监听器就会重新构建输出文件，然后单独运行本地文件服务器来为这些输出文件提供服务。但这意味着，如果重建尚未完成，编辑后重新加载可能会加载到旧的输出文件。对于esbuild的web服务器，如果尚未进行重建，则每个传入的请求都会启动重建，然后等待当前重建完成后再提供文件。这意味着esbuild永远不会提供老版本的构建结果。

请注意，此web服务器仅用于开发。请勿在生产中使用。

参数 Arguments

Serve API有以下几个参数：

# Enable serve mode
--serve

# Set the port
--serve=9000

# Set the host and port (IPv4)
--serve=127.0.0.1:9000

# Set the host and port (IPv6)
--serve=[::1]:9000

# Set the directory to serve
--servedir=www

# Enable HTTPS
--keyfile=your.key --certfile=your.cert

# Specify a fallback HTML file
--serve-fallback=some-file.html

• host
  
  默认情况下，esbuild创建的web服务器在所有IPv4网络接口上可用。这对应于0.0.0.0的主机地址。如果您想配置不同的主机（例如，只在127.0.0.1环回接口上提供服务，而不向网络公开任何内容），可以使用此参数指定主机。
  
  如果你需要使用IPv6而不是IPv4，你只需要指定一个IPv6主机地址。等效于IPv6中的127.0.0.1环回接口为::1，等效于IPv6的0.0.0.0通用接口为::。

• port
  
  HTTP端口可以选择在此处进行配置。如果省略，它将默认为一个开放端口，首选端口范围在8000到8009之间。

• servedir
  
  当传入的请求与生成的所有输出文件路径都不匹配时，可以使用这个配置为esbuild的HTTP服务器配置额外的服务内容目录，这样可以避免404。这样您就可以将esbuild用作通用的本地web服务器。
  
  例如，您可能想要创建一个index.html文件，然后将servedir设置为“.”以服务于当前目录（包括index.html文件）。如果不设置servedir，那么esbuild将只提供生成结果，而不提供任何其他文件。

• keyfile 和 certfile
  
  如果使用keyfile和certfile将私钥和证书传递给esbuild，那么esbuild的web服务器将使用https://协议而不是http://协议。有关详细信息，请参阅启用HTTPS章节内容。

• fallback
  当传入的请求与生成的所有输出文件路径都不匹配时，可以提供一个供esbuild的HTTP服务器使用的HTML文件，这样可以避免404。您可以将其用于自定义的“not found”页面。您还可以将其用作单页应用的入口点。

• onRequest
  对于每个传入的请求都会调用一次这个回调方法，其中包含请求的一些信息。CLI工具使用此回调来打印每个请求的日志信息。时间字段是为请求生成数据的时间，但不包括将请求流式传输到客户端的时间。
  
  请注意，这是在请求完成后调用的。不可能使用此回调以任何方式修改请求。如果你想这样做，你应该在esbuild前面放一个代理。

返回值 Return values

# The CLI will print the host and port like this:

> Local: http://127.0.0.1:8000/

• host：服务的主机ip

• port：服务的端口

启用https（Enabling HTTPS）

默认情况下，esbuild的web服务器使用http://协议。但是，某些现代web功能对于HTTP网站来说是不可用的。如果你想使用这些功能，那么你需要告诉esbuild使用https://协议。

要使用esbuild启用HTTPS，请执行以下操作：

1. 生成自签名证书。有很多方法可以做到这一点。这里有一种方法，假设您安装了openssl命令：

openssl req -x509 -newkey rsa:4096 -keyout your.key -out your.cert -days 9999 -nodes -subj /CN=127.0.0.1 

2. 使用keyfile和certfile服务参数将.key和.cert传递给esbuild。

3. 加载页面时，点击忽略浏览器中的warning警告（自签名证书是不安全的，但这无关紧要，因为我们只是在进行本地开发）。

如果您有比这更复杂的需求，您仍然可以在esbuild前面放置一个代理，并将其用于HTTPS。请注意，如果在加载页面时看到消息Client sent an HTTP request to an HTTPS server，则说明您使用的协议不正确。需要将浏览器URL栏中的http://替换为https://。

请记住，esbuild的HTTPS支持与安全性无关。在esbuild中启用HTTPS的唯一原因是，浏览器使得在不跳过这些额外的障碍的情况下，无法使用某些现代web功能进行本地开发。请不要将esbuild的开发服务器用于任何需要安全的内容。它只用于本地开发，没有考虑任何生产环境。

自定义服务 Customizing server behavior

esbuild的本地服务器来自定义服务器行为是不可能的。相反，应该通过在esbuild前面放置一个代理来定制行为。

下面是一个简单的代理服务器示例，它使用node内置的http模块。它添加了一个自定义的404页面，而不是esbuild的默认404页面：

import * as esbuild from 'esbuild'
import http from 'node:http'

// Start esbuild's server on a random local port
let ctx = await esbuild.context({
  // ... your build options go here ...
})

// The return value tells us where esbuild's local server is
let { host, port } = await ctx.serve({ servedir: '.' })

// Then start a proxy server on port 3000
http.createServer((req, res) => {
  const options = {
    hostname: host,
    port: port,
    path: req.url,
    method: req.method,
    headers: req.headers,
  }

  // Forward each incoming request to esbuild
  const proxyReq = http.request(options, proxyRes => {
    // If esbuild returns "not found", send a custom 404 page
    if (proxyRes.statusCode === 404) {
      res.writeHead(404, { 'Content-Type': 'text/html' })
      res.end('<h1>A custom 404 page</h1>')
      return
    }

    // Otherwise, forward the response from esbuild to the client
    res.writeHead(proxyRes.statusCode, proxyRes.headers)
    proxyRes.pipe(res, { end: true })
  })

  // Forward the body of the request to esbuild
  req.pipe(proxyReq, { end: true })
}).listen(3000)

这段代码在本地一个随机端口上启动esbuild的服务器，然后在端口3000上启动代理服务器。在开发过程中，您将加载http://localhost:3000在您的浏览器中，它与代理进行对话。此示例演示了在esbuild处理完请求后修改响应，但您也可以在esuild处理请求之前修改或替换请求。

你可以用这样的代理做很多事情，包括：

• 注入你自己的404页面（上面的例子）

• 自定义路由到文件系统上文件的映射

• 将某些路由重定向到API服务器，而不是esbuild

如果你有更高级的需求，你也可以使用真正的代理，比如nginx。

结语

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

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

（本文完）

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