加载器

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。