載入器

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' 匯入屬性。

index.ts複製

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 物件放入包中。

const 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。

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",
};

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!";

napi

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

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

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

sqlite

SQLite 載入器。 需要使用 with { "type": "sqlite" } 匯入屬性。

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

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

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

你可以使用 "embed" 屬性改變此行為：

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

html

HTML 載入器。 預設用於 .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="本地圖片" />
    <img src="https://example.com/image.jpg" alt="外部圖片" />
    <script type="module" src="./script.js"></script>
  </body>
</html>

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

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="本地圖片" />
    <img src="https://example.com/image.jpg" alt="外部圖片" />
    <script type="module" src="./output-ALSO-HASHED.js"></script>
  </body>
</html>

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

css

CSS 載入器。 預設用於 .css。

CSS 檔案可以直接匯入。打包器會解析並打包這些檔案，處理 @import 語句和 url() 引用。

import "./styles.css";

打包時，Bun 會將所有匯入的 CSS 檔案合併為輸出目錄中的一個 .css 檔案。

.my-class {
  background: url("./image.png");
}

sh

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

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

bun run ./script.sh

file

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

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

// logo.ts
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。