加载器

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

使用 TypeScript 7.1 或更高版本时，@types/bun 会根据 type 属性为这些导入提供类型：type: "text" 导入的类型为 string，type: "sqlite" 导入的类型为 Database。较旧的 TypeScript 版本仅根据文件扩展名为导入提供类型。

内置加载器

`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": "[email protected]"
}

export default {
  name: "John Doe",
  age: 35,
  email: "[email protected]",
};

`jsonc`

含注释的 JSON（JSONC）加载器。 默认用于 .jsonc。 JSONC（带注释的 JSON）文件可以直接导入。Bun 会解析这些文件，并去除注释和尾随逗号。

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

打包时，Bun 会将解析后的 JSONC 以内联方式作为 JavaScript 对象放入包中，其行为与 json 加载器相同。

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

Bun 会自动针对 tsconfig.json、jsconfig.json、package.json 和 bun.lock 文件使用 jsonc 加载器。

`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 = "[email protected]"

export default {
  name: "John Doe",
  age: 35,
  email: "[email protected]",
};

`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: [email protected]

export default {
  name: "John Doe",
  age: 35,
  email: "[email protected]",
};

`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>[email protected]</email>
  <role>admin</role>
  <role>editor</role>
</user>

export default {
  user: {
    "@id": "1",
    name: "John Doe",
    email: "[email protected]",
    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);

在打包器中，Bun 使用 file 加载器处理 .node 文件。

`sqlite`

SQLite 加载器。 需要使用 with { "type": "sqlite" } 导入属性。在运行时和打包器中，可以直接导入 SQLite 数据库。Bun 会使用 bun:sqlite 加载数据库。

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

sqlite 加载器仅在目标为 bun 时受支持。

默认情况下，Bun 不会将磁盘上的数据库文件打包到最终输出中。数据库文件会保留在包外部，因此你可以使用从其他位置加载的数据库。你可以使用 "embed" 属性改变此行为：

// 将数据库嵌入包内
import db from "./my.db" with { type: "sqlite", embed: "true" };

使用独立可执行文件时，Bun 会将数据库嵌入单文件可执行文件中。否则，嵌入的数据库会被复制到输出目录 outdir，并带有哈希文件名。

`html`

HTML 加载器。 默认用于 .html。 html 加载器会处理 HTML 文件，并打包其中引用的所有资源。它会：

打包并哈希引用的 JavaScript 文件（<script src="...">）
打包并哈希引用的 CSS 文件（<link rel="stylesheet" href="...">）
为引用的图片生成哈希（<img src="...">）
保留外部 URL（默认情况下，任何以 http:// 或 https:// 开头的 URL）

例如，给定如下 HTML 文件：

src/index.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 文件：

dist/index.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 标签提取为入口点，并将其他资源作为外部资源处理。

支持的 HTML 选择器列表

选择器包括：

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]

HTML 加载器在不同场景下的行为html 加载器的行为取决于它的使用方式：

静态构建：运行 bun build ./index.html 时，Bun 会生成一个包含所有已打包并哈希处理资源的静态网站。
运行时：运行 bun run server.ts 时（其中 server.ts 导入了 HTML 文件），Bun 会在开发过程中即时打包资源，从而支持热模块替换等功能。
全栈构建：运行 bun build --target=bun server.ts 时（其中 server.ts 导入了 HTML 文件），该导入会解析为一个清单对象，Bun.serve 会使用它在生产环境中提供预先打包的资源。

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

公共路径	解析后的导入
`""`（默认）	`./logo.svg`
`"/assets/"`	`/assets/logo.svg`
`"https://cdn.example.com/"`	`https://cdn.example.com/logo.svg`

naming.asset 的值决定了复制文件的位置和文件名。

核心

开发服务器

资源处理

可执行文件

扩展

优化

迁移

内置加载器

`js`

`jsx`

`ts`

`tsx`

`json`

`jsonc`

`toml`

`yaml`

`xml`

`text`

`napi`

`sqlite`

`html`

`css`

`sh`

`file`

​内置加载器

​js

​jsx

​ts

​tsx

​json

​jsonc

​toml

​yaml

​xml

​text

​napi

​sqlite

​html

​css

​sh

​file

内置加载器

`js`

`jsx`

`ts`

`tsx`

`json`

`jsonc`

`toml`

`yaml`

`xml`

`text`

`napi`

`sqlite`

`html`

`css`

`sh`

`file`