HTML & 静态站点 – Bundler | Bun 文档

Bun 的打包器对 HTML 提供一流支持。无需配置即可构建静态站点、登录页面和 Web 应用程序。只需将 Bun 指向您的 HTML 文件，它就会处理其他所有事情。

index.html
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./styles.css" />
    <script src="./app.ts" type="module"></script>
  </head>
  <body>
    <img src="./logo.png" />
  </body>
</html>

首先，将 HTML 文件传递给 bun。

bun ./index.html

Bunv1.3在6.62毫秒内准备就绪

https://:3000/

按h+Enter显示快捷键

Bun 的开发服务器提供功能强大的特性，无需任何配置

自动打包 - 打包并提供您的 HTML、JavaScript 和 CSS
多入口支持 - 处理多个 HTML 入口点和 glob 入口点
现代 JavaScript - 开箱即用的 TypeScript 和 JSX 支持
智能配置 - 读取 tsconfig.json 以获取路径、JSX 选项、实验性装饰器等
插件 - 用于 TailwindCSS 等的插件
ESM & CommonJS - 在您的 JavaScript、TypeScript 和 JSX 文件中使用 ESM 和 CommonJS
CSS 打包和压缩 - 打包 <link> 标签和 @import 语句中的 CSS
资产管理
- 图像和资产的自动复制和哈希
- 重写 JavaScript、CSS 和 HTML 中的资产路径

单页应用程序 (SPA)

当您将单个 .html 文件传递给 Bun 时，Bun 将其用作所有路径的备用路由。这使其非常适合使用客户端路由的单页应用程序。

bun index.html

Bunv1.3在6.62毫秒内准备就绪

https://:3000/

按h+Enter显示快捷键

您的 React 或其他 SPA 将开箱即用 — 无需配置。所有路由，如 /about、/users/123 等，都将提供相同的 HTML 文件，让您的客户端路由处理导航。

index.html
<!doctype html>
<html>
  <head>
    <title>My SPA</title>
    <script src="./app.tsx" type="module"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

多页应用程序 (MPA)

有些项目有多个单独的路由或 HTML 文件作为入口点。要支持多个入口点，请将它们全部传递给 bun

bun ./index.html ./about.html

Bunv1.3在6.62毫秒内准备就绪

https://:3000/

路由

/./index.html

/about./about.html

按h+Enter显示快捷键

这将提供

index.html 在 /
about.html 在 /about

Glob 模式

要指定多个文件，您可以使用以 .html 结尾的 glob 模式

bun ./**/*.html

Bunv1.3在6.62毫秒内准备就绪

https://:3000/

路由

/./index.html

/about./about.html

按h+Enter显示快捷键

路径规范化

基本路径是从所有文件中最长的共同前缀中选择的。

bun ./index.html ./about/index.html ./about/foo/index.html

Bunv1.3在6.62毫秒内准备就绪

https://:3000/

路由

/./index.html

/about./about/index.html

/about/foo./about/foo/index.html

按h+Enter显示快捷键

JavaScript、TypeScript 和 JSX

Bun 的转译器原生实现了 JavaScript、TypeScript 和 JSX 支持。了解有关 Bun 中加载器的更多信息。

Bun 的转译器也在运行时使用。

ES 模块 & CommonJS

您可以在 JavaScript、TypeScript 和 JSX 文件中使用 ESM 和 CJS。Bun 将自动处理转译和打包。

没有预构建或单独的优化步骤。所有这些都同时完成。

了解有关 Bun 中模块解析的更多信息。

CSS

Bun 的 CSS 解析器也原生实现（大约 58,000 行 Zig 代码）。

它也是一个 CSS 打包器。您可以在 CSS 文件中使用 @import 导入其他 CSS 文件。

例如

styles.css
@import "./abc.css";

.container {
  background-color: blue;
}

abc.css
body {
  background-color: red;
}

这将输出

styles.css
body {
  background-color: red;
}

.container {
  background-color: blue;
}

在 CSS 中引用本地资产

您可以在 CSS 文件中引用本地资产。

styles.css
body {
  background-image: url("./logo.png");
}

这将 ./logo.png 复制到输出目录，并重写 CSS 文件中的路径以包含内容哈希。

styles.css
body {
  background-image: url("./logo-[ABC123].png");
}

在 JavaScript 中导入 CSS

要将 CSS 文件与 JavaScript 文件关联起来，您可以在 JavaScript 文件中导入它。

app.ts
import "./styles.css";
import "./more-styles.css";

这将在输出目录中生成 ./app.css 和 ./app.js。所有从 JavaScript 导入的 CSS 文件将被打包到每个入口点的一个 CSS 文件中。如果您从多个 JavaScript 文件导入同一个 CSS 文件，它将只包含在输出 CSS 文件中一次。

插件

开发服务器支持插件。

Tailwind CSS

要使用 TailwindCSS，请安装 bun-plugin-tailwind 插件

# Or any npm client
bun install --dev bun-plugin-tailwind

然后，将插件添加到您的 bunfig.toml 中

[serve.static]
plugins = ["bun-plugin-tailwind"]

然后，通过 <link> 标签、CSS 中的 @import 或 JavaScript 中的 import 在您的 HTML 中引用 TailwindCSS。

index.html

styles.css

app.ts

index.html
<!-- Reference TailwindCSS in your HTML -->
<link rel="stylesheet" href="tailwindcss" />

styles.css
/* Import TailwindCSS in your CSS */
@import "tailwindcss";

app.ts
/* Import TailwindCSS in your JavaScript */
import "tailwindcss";

只需其中一项，而不是全部三项。

将控制台日志从浏览器回显到终端

Bun 的开发服务器支持将控制台日志从浏览器流式传输到终端。

要启用，请传递 --console CLI 标志。

bun ./index.html --console

Bunv1.3在6.62毫秒内准备就绪

https://:3000/

按h+Enter显示快捷键

每次调用 console.log 或 console.error 都将广播到启动服务器的终端。这对于在运行服务器的同一位置查看来自浏览器的错误很有用。这对于监视终端输出的 AI 代理也很有用。

在内部，这会重用来自热模块重新加载的现有 WebSocket 连接来发送日志。

在浏览器中编辑文件

Bun 的前端开发服务器支持 Chrome DevTools 中的自动工作区文件夹，它允许您保存对浏览器中文件的编辑。

Bun's frontend dev server has support for Automatic Workspace Folders in Chrome DevTools, which lets you save edits to files in the browser.

工作原理

Bun 的开发服务器会自动将 /.well-known/appspecific/com.chrome.devtools.json 路由添加到服务器。

此路由返回一个具有以下形状的 JSON 对象

{
  "workspace": {
    "root": "/path/to/your/project",
    "uuid": "a-unique-identifier-for-this-workspace"
  }
}

出于安全原因，这仅在以下情况下启用

请求来自 localhost、127.0.0.1 或 ::1。
热模块重新加载已启用。
chromeDevToolsAutomaticWorkspaceFolders 标志设置为 true 或 undefined。
没有其他路由与请求匹配。

您可以通过在 Bun.serve 的选项中传入 development: { chromeDevToolsAutomaticWorkspaceFolders: false } 来禁用此功能。

键盘快捷键

当服务器运行时

o + Enter - 在浏览器中打开
c + Enter - 清除控制台
q + Enter (或 Ctrl+C) - 退出服务器

为生产构建

当您准备好部署时，使用 bun build 创建优化的生产捆绑包

CLI

API

CLI
bun build ./index.html --minify --outdir=dist

API
Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: {
    whitespace: true,
    identifiers: true,
    syntax: true,
  }
});

目前，插件仅通过 Bun.build 的 API 或通过 bunfig.toml 与前端开发服务器一起受支持 - 尚不支持 bun build 的 CLI。

观察模式

您可以运行 bun build --watch 来监视更改并自动重建。这对于库开发非常有用。

您从未见过如此快速的观察模式。

插件 API

需要更多控制？通过 JavaScript API 配置打包器，并使用 Bun 内置的 HTMLRewriter 预处理 HTML。

await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,

  plugins: [
    {
      // A plugin that makes every HTML tag lowercase
      name: "lowercase-html-plugin",
      setup({ onLoad }) {
        const rewriter = new HTMLRewriter().on("*", {
          element(element) {
            element.tagName = element.tagName.toLowerCase();
          },
          text(element) {
            element.replace(element.text.toLowerCase());
          },
        });

        onLoad({ filter: /\.html$/ }, async args => {
          const html = await Bun.file(args.path).text();

          return {
            // Bun's bundler will scan the HTML for <script> tags, <link rel="stylesheet"> tags, and other assets
            // and bundle them automatically
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

处理了什么？

Bun 自动处理所有常见的 Web 资产

脚本 (<script src>) 通过 Bun 的 JavaScript/TypeScript/JSX 打包器运行
样式表 (<link rel="stylesheet">) 通过 Bun 的 CSS 解析器和打包器运行
图像 (<img>, <picture>) 被复制和哈希
媒体 (<video>, <audio>, <source>) 被复制和哈希
任何 <link> 标签，如果其 href 属性指向本地文件，则会被重写为新路径并哈希

所有路径都相对于您的 HTML 文件解析，从而可以轻松地根据需要组织项目。

这是一个正在进行中的工作

需要更多插件
需要更多用于资产处理等方面的配置选项
需要一种方法来配置 CORS、标头等

如果您想提交 PR，大部分代码在此处。您甚至可以将该文件复制粘贴到您的项目中并将其用作起点。

工作原理

这是 Bun 对 JavaScript 中 HTML 导入支持的一个小包装。

为您的前端添加后端

要为您的前端添加后端，您可以使用 Bun.serve 中的 "routes" 选项。

在全栈文档中了解更多信息。