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