檔案型別

Bun 打包器實現了一組預設載入器。一般來說，打包器和執行環境支援相同的檔案型別集合。

.js .cjs .mjs .mts .cts .ts .tsx .jsx .css .json .jsonc .json5 .toml .yaml .yml .xml .txt .text .md .markdown .wasm .node .html .sh

Bun 使用副檔名來選擇解析檔案的內建 載入器。每個載入器都有一個名稱，例如 js、tsx 或 json。在建置擴充套件 Bun 功能的外掛時，會使用這些名稱。

若要顯式指定載入器，請使用 type 匯入屬性。

import my_toml from "./my_file" with { type: "toml" };
// 或者通過動態匯入
const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

內建載入器

js

JavaScript。.cjs 和 .mjs 的預設載入器。

解析程式碼並應用一組預設轉換，例如死程式碼消除和樹搖。Bun 不會向下轉換語法。

jsx

JavaScript + JSX。.js 和 .jsx 的預設載入器。

與 js 載入器相同，但支援 JSX 語法。預設情況下，Bun 會將 JSX 向下轉換為純 JavaScript；具體行為取決於 tsconfig.json 中的 jsx* 編譯器選項。請參閱 TypeScript 文件中關於 JSX 的內容。

ts

TypeScript 載入器。.ts、.mts 和 .cts 的預設載入器。

剝離所有 TypeScript 語法，然後行為與 js 載入器相同。Bun 不做型別檢查。

tsx

TypeScript + JSX 載入器。.tsx 的預設載入器。將 TypeScript 和 JSX 轉譯為普通 JavaScript。

json

JSON 載入器。.json 的預設載入器。

JSON 檔案可以直接匯入。

import pkg from "./package.json";
pkg.name; // => "my-package"

打包時，Bun 會將解析後的 JSON 作為 JavaScript 物件內聯到打包檔案中。

var pkg = {
  name: "my-package",
  // ... 其他欄位
};
pkg.name;

如果將 .json 檔案作為入口點傳遞給打包器，Bun 會將其轉換為 .js 模組，並通過 export default 匯出解析後的物件。

{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

jsonc

帶註釋的 JSON 載入器。.jsonc 的預設載入器。

JSONC（帶註釋的 JSON）檔案可以直接匯入。Bun 會解析這些檔案，並移除註釋和尾隨逗號。

import config from "./config.jsonc";
console.log(config);

打包時，Bun 會將解析後的 JSONC 作為 JavaScript 物件內聯到打包檔案中，其行為與 json 載入器相同。

var config = {
  option: "value",
};

toml

TOML 載入器。.toml 的預設載入器。

TOML 檔案可以直接匯入。Bun 使用其快速的原生 TOML 解析器解析這些檔案。

import config from "./bunfig.toml";
config.logLevel; // => "debug"

// 使用匯入屬性：
// import myCustomTOML from './my.config' with {type: "toml"};

打包時，Bun 會將解析後的 TOML 作為 JavaScript 物件內聯到打包檔案中。

var config = {
  logLevel: "debug",
  // ...其他欄位
};
config.logLevel;

如果將 .toml 檔案作為入口點傳遞，Bun 會將其轉換為 .js 模組，並通過 export default 匯出解析後的物件。

name = "John Doe"
age = 35
email = "johndoe@example.com"

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

yaml

YAML 載入器。.yaml 和 .yml 的預設載入器。

YAML 檔案可以直接匯入。Bun 使用其快速的原生 YAML 解析器解析這些檔案。

import config from "./config.yaml";
console.log(config);

// 使用匯入屬性：
import data from "./data.txt" with { type: "yaml" };

打包時，Bun 會將解析後的 YAML 作為 JavaScript 物件內聯到打包檔案中。

var config = {
  name: "my-app",
  version: "1.0.0",
  // ...其他欄位
};

如果將 .yaml 或 .yml 檔案作為入口點傳遞，Bun 會將其轉換為 .js 模組，並通過 export default 匯出解析後的物件。

name: John Doe
age: 35
email: johndoe@example.com

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

json5

JSON5 載入器。.json5 的預設載入器。

JSON5 檔案可以直接匯入。Bun 使用其快速的原生 JSON5 解析器解析這些檔案。JSON5 是 JSON 的超集，增加了註釋、尾隨逗號、未加引號的鍵、單引號字串等特性。

import config from "./config.json5";
console.log(config);

// 通過匯入屬性：
import data from "./data.txt" with { type: "json5" };

打包時，Bun 會將解析後的 JSON5 作為 JavaScript 物件內聯到打包檔案中。

var config = {
  name: "my-app",
  version: "1.0.0",
  // ...其他欄位
};

如果將 .json5 檔案作為入口點傳遞，Bun 會將其轉換為 .js 模組，並通過 export default 匯出解析後的物件。

{
  // 設定
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
}

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

xml

XML 載入器。.xml 的預設載入器。

XML 檔案可以直接匯入。Bun 使用其原生 XML 1.0 解析器，將其解析為 Bun.XML.parse 所使用的緊湊物件結構：

• 根元素對應一個鍵
• 屬性對應 "@name" 鍵
• 重複的子元素對應陣列
• 屬性或子元素旁的文本對應 "#text"
• 所有值均為字串

import doc from "./config.xml";
console.log(doc.config["@version"]);

// 通過匯入屬性：
import feed from "./export.rss" with { type: "xml" };

打包時，Bun 會將解析後的 XML 作為 JavaScript 物件內聯到打包檔案中。

var doc = {
  config: {
    "@version": "2",
    // ...other fields
  },
};

如果將 .xml 檔案作為入口點傳遞，Bun 會將其轉換為 .js 模組，並通過 export default 匯出解析後的物件。

<user id="1">
  <name>John Doe</name>
  <email>johndoe@example.com</email>
  <role>admin</role>
  <role>editor</role>
</user>

export default {
  user: {
    "@id": "1",
    name: "John Doe",
    email: "johndoe@example.com",
    role: ["admin", "editor"],
  },
};

text

文本載入器。.txt 和 .text 的預設載入器。

文本檔案可以直接匯入。Bun 會讀取檔案，並將其作為字串傳回。

import contents from "./file.txt";
console.log(contents); // => "Hello, world!"

// 以文本形式匯入 html 檔案
// 可以通過 'type' 屬性覆蓋預設載入器。
import html from "./index.html" with { type: "text" };

建置過程中引用該檔案時，Bun 會將檔案內容作為字串內聯到打包檔案中。

var contents = `Hello, world!`;
console.log(contents);

如果將 .txt 檔案作為入口點傳遞，Bun 會將其轉換為 .js 模組，並通過 export default 匯出檔案內容。

Hello, world!

export default "Hello, world!";

md

Markdown 載入器。.md 和 .markdown 的預設載入器。

Markdown 檔案可以直接匯入。Bun 會將檔案渲染為 HTML，並將 HTML 作為字串傳回。

import html from "./README.md";
console.log(html); // => "<h1>Title</h1>\n"

// 通過匯入屬性（`markdown` 是 `md` 的別名）：
import notes from "./notes.txt" with { type: "md" };

打包時，Bun 會將渲染後的 HTML 作為字串內聯到打包檔案中。

napi

本地擴充套件載入器。.node 的預設載入器。

執行環境可以直接匯入本地擴充套件。

import addon from "./addon.node";
console.log(addon);

在打包器中，Bun 使用 file 載入器處理 .node 檔案。

sqlite

SQLite 載入器。with { "type": "sqlite" } 匯入屬性。

在執行環境和打包器中，可以直接匯入 SQLite 資料庫。Bun 使用 bun:sqlite 載入資料庫。

import db from "./my.db" with { type: "sqlite" };

僅當 target 為 bun 時，才支援 sqlite 載入器。

預設情況下，資料庫不會打包進包中：Bun 不會將磁碟上的資料庫檔案打包到最終輸出中，因此你可以使用從其他位置載入的資料庫。

你可以通過 "embed" 屬性改變這個行為：

// 將資料庫嵌入包中
import db from "./my.db" with { type: "sqlite", embed: "true" };

使用獨立執行檔時，Bun 會將資料庫嵌入單檔案執行檔中。

否則，嵌入資料庫會被複制到 outdir，並使用雜湊後的檔名。

html

html 載入器會處理 HTML 檔案並打包所有引用的資源。它：

• 打包並雜湊引用的 JavaScript 檔案（<script src="...">）
• 打包並雜湊引用的 CSS 檔案（<link rel="stylesheet" href="...">）
• 雜湊引用的影像（<img src="...">）
• 保留外部 URL（預設情況下，任何以 http:// 或 https:// 開頭的 URL）

範例，假設有如下 HTML 檔案：

<!DOCTYPE html>
<html>
  <body>
    <img src="./image.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./script.js"></script>
  </body>
</html>

Bun 會輸出一個包含已打包資源的新 HTML 檔案：

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./output-ALSO-HASHED.js"></script>
  </body>
</html>

該載入器使用 lol-html 將 script 和 link 標籤提取為入口點，並將其他資源作為外部資源處理。

選擇器列表如下：

• audio[src]
• img[src]
• img[srcset]
• link[as='font'][href], link[type^='font/'][href]
• link[as='image'][href]
• link[as='style'][href]
• link[as='video'][href], link[as='audio'][href]
• link[as='worker'][href]
• link[rel='icon'][href], link[rel='apple-touch-icon'][href]
• link[rel='manifest'][href]
• link[rel='stylesheet'][href]
• script[src]
• source[src]
• source[srcset]
• video[poster]
• video[src]

css

CSS 載入器。.css 的預設載入器。

CSS 檔案可以直接匯入。這在打包 HTML時尤為有用，此時 CSS 會與 HTML 一起打包。

import "./styles.css";

匯入不會傳回任何值；它僅用於其副作用。

sh 載入器

Bun Shell 載入器。.sh 檔案的預設載入器。

此載入器解析 Bun Shell 指令碼。它僅在啟動 Bun 本身時受支援，因此在打包器或執行環境中不可用。

bun run ./script.sh

file

檔案載入器。所有未識別檔案型別的預設載入器。

檔案載入器將匯入解析為被匯入檔案的 路徑/URL，通常用來引用媒體或字型資源。

import logo from "./logo.svg";
console.log(logo);

在執行環境，Bun 會檢查 logo.svg 檔案是否存在，並將匯入解析為磁碟上的絕對路徑。

bun run logo.ts
/path/to/project/logo.svg

在打包器中，Bun 會將檔案原樣複製到 outdir，匯入則解析為指向已複製檔案的相對路徑。

var logo = "./logo.svg";
console.log(logo);

如果設定了 publicPath，匯入會使用其值作為字首來構造絕對路徑/URL。

此載入器複製檔案到 outdir，複製檔名由 naming.asset 的值確定。

// TypeScript 錯誤
// 無法找到模組 './logo.svg' 或其對應的型別宣告。

declare module "*.svg" {
  const content: string;
  export default content;
}