Bun文档教程

简体中文

English
繁體中文

简体中文

English
繁體中文

Appearance

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

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。

bash
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 入口点和 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 将其用作所有路径的回退路由。这使其非常适合使用客户端路由的单页应用：

bash
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 文件，让您的客户端路由器处理导航。

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：

bash
bun ./index.html ./about.html
txt
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 处的 about.html

Glob 模式 ​

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

bash
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

路径规范化 ​

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

bash
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 中加载器的更多信息。

NOTE

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

ES 模块和 CommonJS ​

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

没有预构建或单独的优化步骤。所有操作同时完成。

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

CSS ​

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

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

例如：

css
@import "./abc.css";

.container {
  background-color: blue;
}
css
body {
  background-color: red;
}

这将输出：

css
body {
  background-color: red;
}

.container {
  background-color: blue;
}

在 CSS 中引用本地资源 ​

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

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

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

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

在 JavaScript 中导入 CSS ​

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

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

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

插件 ​

开发服务器支持插件。

Tailwind CSS ​

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

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

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

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

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

index.html"> ​

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

styles.css"> ​

css
@import "tailwindcss";

app.ts"> ​

ts
import "tailwindcss";

内联环境变量 ​

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

开发服务器（运行时） ​

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

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

NOTE

这仅适用于字面量 `process.env.FOO` 引用，不适用于 `import.meta.env` 或间接访问如 `const env = process.env; env.FOO`。

如果环境变量未设置，您可能会在浏览器中看到运行时错误，如 ReferenceError: process is not defined。

然后运行开发服务器：

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

为生产构建 ​

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

CLI"> ​

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

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

API"> ​

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

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

示例 ​

给定此源文件：

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

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

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

打包输出将包含：

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

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

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

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

bash
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 创建优化的生产包：

CLI"> ​

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

API"> ​

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

监听模式 ​

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

插件 API ​

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

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 文件解析，使您可以轻松按任何方式组织项目。

工作原理 ​

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

为前端添加后端 ​

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

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

Bun学习网由www.bunjs.com.cn整理维护

MIT Licensed | Copyright © 2023-present