HTML和静态网站

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。

terminal

bun ./index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

Bun的开发服务器提供了零配置的强大功能：

自动打包 - 打包和提供您的HTML、JavaScript和CSS
多入口支持 - 处理多个HTML入口点和通配符入口点
现代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会将其用作所有路径的回退路由。这使其非常适合使用客户端路由的单页应用：

terminal

bun index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

您的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：

terminal

bun ./index.html ./about.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

这将提供：

index.html 在 /
about.html 在 /about

通配符模式

要指定多个文件，您可以使用以[.html]结尾的通配符模式：

terminal

bun ./**/*.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

路径规范化

基础路径从所有文件中最长的公共前缀中选择。

terminal

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

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about/index.html
  /about/foo ./about/foo/index.html
Press h + Enter to show shortcuts

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文件。例如：

@import "./abc.css";

.container {
  background-color: blue;
}

这输出：

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文件中导入它。

https://mintcdn.com/teemo/2s-4Z6VdGqiCeBNX/icons/typescript.svg?fit=max&auto=format&n=2s-4Z6VdGqiCeBNX&q=85&s=087b260066909db1cd3e9c7292bc34b2

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插件：

terminal

# 或任何npm客户端
bun install --dev bun-plugin-tailwind

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

bunfig.toml

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

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

index.html
styles.css
app.ts

index.html

<!-- 在HTML中引用TailwindCSS -->
<link rel="stylesheet" href="tailwindcss" />

styles.css

@import "tailwindcss";

app.ts

import "tailwindcss";

只需要其中一种，而不是三种都需要。

内联环境变量

Bun可以在构建时将JavaScript和TypeScript中的process.env.*引用替换为它们的实际值。这对于将API URL或功能标志等配置注入到您的前端代码中很有用。

开发服务器（运行时）

在使用bun ./index.html时要内联环境变量，请在您的bunfig.toml中配置env选项：

bunfig.toml

[serve.static]
env = "PUBLIC_*"  # 只内联以PUBLIC_开头的环境变量（推荐）
# env = "inline"  # 内联所有环境变量
# env = "disable" # 禁用环境变量替换（默认）

这仅适用于字面量process.env.FOO引用，不适用于import.meta.env或间接访问如const env = process.env; env.FOO。如果未设置环境变量，您可能会在浏览器中看到运行时错误，如ReferenceError: process is not defined。

然后运行开发服务器：

terminal

PUBLIC_API_URL=https://api.example.com bun ./index.html

构建生产版本

在为生产构建静态HTML时，使用env选项内联环境变量：

terminal

# 内联所有环境变量
bun build ./index.html --outdir=dist --env=inline

# 仅内联具有特定前缀的环境变量（推荐）
bun build ./index.html --outdir=dist --env=PUBLIC_*

build.ts

// 内联所有环境变量
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", 
});

// 仅内联具有特定前缀的环境变量（推荐）
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", 
});

示例

给定此源文件：

app.ts

const apiUrl = process.env.PUBLIC_API_URL;
console.log(`API URL: ${apiUrl}`);

并使用PUBLIC_API_URL=https://api.example.com运行：

terminal

PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_*

打包的输出将包含：

https://mintcdn.com/teemo/2s-4Z6VdGqiCeBNX/icons/javascript.svg?fit=max&auto=format&n=2s-4Z6VdGqiCeBNX&q=85&s=f214c10aa11d8f0f585845867937d9fd

dist/app.js

const apiUrl = "https://api.example.com";
console.log(`API URL: ${apiUrl}`);

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

Bun的开发服务器支持将浏览器中的控制台日志流式传输到终端。要启用，请传递--console CLI标志。

terminal

bun ./index.html --console

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

每次调用console.log或console.error都会广播到启动服务器的终端。这对于在运行服务器的同一位置查看浏览器中的错误很有用。这对于监视终端输出的AI代理也很有用。在内部，这重用热模块重载的现有WebSocket连接来发送日志。

在浏览器中编辑文件

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

键盘快捷键

服务器运行时：

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

构建生产版本

准备部署时，使用bun build创建优化的生产包：

terminal

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

build.ts

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

目前，插件仅通过Bun.build的API或通过前端开发服务器的bunfig.toml支持

尚未在bun build的CLI中支持。

监视模式

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

您从未见过如此快的监视模式。

插件API

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

build.ts

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

  plugins: [
    {
      // 一个使每个HTML标签小写的插件
      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的打包器将扫描HTML中的<script>标签、<link rel="stylesheet">标签和其他资源
            // 并自动打包它们
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

处理了哪些内容？

Bun自动处理所有常见Web资源：

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

所有路径都相对于您的HTML文件解析，使您能够轻松地按任何方式组织您的项目。

这是正在进行的工作

需要更多插件
需要更多配置选项，如资源处理
需要一种配置CORS、头部等的方法

工作原理

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

为前端添加后端

要为前端添加后端，您可以使用Bun.serve中的”routes”选项。在全栈文档中了解更多信息。

Core

Development Server

Asset Processing

Single File Executable

Extensions

Optimization

Migration

单页应用(SPA)

多页应用(MPA)

通配符模式

路径规范化

JavaScript、TypeScript和JSX

ES模块和CommonJS

CSS

在CSS中引用本地资源

在JavaScript中导入CSS

插件

Tailwind CSS

内联环境变量

开发服务器（运行时）

构建生产版本

示例

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

在浏览器中编辑文件

键盘快捷键

构建生产版本

监视模式

插件API

处理了哪些内容？

工作原理

为前端添加后端

Core

Development Server

Asset Processing

Single File Executable

Extensions

Optimization

Migration

​单页应用(SPA)

​多页应用(MPA)

​通配符模式

​路径规范化

​JavaScript、TypeScript和JSX

​ES模块和CommonJS

​CSS

​在CSS中引用本地资源

​在JavaScript中导入CSS

​插件

​Tailwind CSS

​内联环境变量

​开发服务器（运行时）

​构建生产版本

​示例

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

​在浏览器中编辑文件

​键盘快捷键

​构建生产版本

​监视模式

​插件API

​处理了哪些内容？

​工作原理

​为前端添加后端

单页应用(SPA)

多页应用(MPA)

通配符模式

路径规范化

JavaScript、TypeScript和JSX

ES模块和CommonJS

CSS

在CSS中引用本地资源

在JavaScript中导入CSS

插件

Tailwind CSS

内联环境变量

开发服务器（运行时）

构建生产版本

示例

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

在浏览器中编辑文件

键盘快捷键

构建生产版本

监视模式

插件API

处理了哪些内容？

工作原理

为前端添加后端