加载器

Bun 打包器内置了一组加载器。

一般来说：打包器和运行时默认支持相同的文件类型。

.js .cjs .mjs .mts .cts .ts .tsx .jsx .css .json .jsonc .toml .yaml .yml .txt .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 语法。默认情况下，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"

在打包时，解析后的 JSON 会以内联的 JavaScript 对象形式插入到包内。

const pkg = {
  name: "my-package",
  // ... 其他字段
};

pkg.name;

如果将 .json 文件作为打包器的入口点传入，则会将其转换为一个通过 export default 导出解析后对象的 .js 模块。

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

打包时，解析后的 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"};

打包时，解析后的 TOML 会以内联的 JavaScript 对象形式插入包内。

var config = {
  logLevel: "debug",
  // ...其他字段
};
config.logLevel;

如果将 .toml 文件作为入口点传入，则会将其转换为一个通过 export default 导出解析后对象的 .js 模块。

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

打包时，解析后的 YAML 会以内联的 JavaScript 对象形式插入包内。

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

如果将 .yaml 或 .yml 文件作为入口点传入，则会将其转换为一个通过 export default 导出解析后对象的 .js 模块。

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

// via import attribute:
import feed from "./export.rss" with { type: "xml" };

打包时，解析后的 XML 会以内联的 JavaScript 对象形式插入包内。

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

如果将 .xml 文件作为入口点传入，则会将其转换为一个通过 export default 导出解析后对象的 .js 模块。

<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。文本文件可以直接导入。文件会被读取并作为字符串返回。

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

// 将 html 文件作为文本导入
// "type" 属性会覆盖默认加载器。
import html from "./index.html" with { type: "text" };

构建时，文件内容以内联字符串形式插入包内。

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

如果将 .txt 文件作为入口点传入，则会将其转换为一个通过 export default 导出文件内容的 .js 模块。

Hello, world!

export default "Hello, world!";

`napi`

本地扩展加载器。 默认用于 .node。在运行时，可以直接导入本地扩展。

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

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

`sqlite`

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

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

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

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

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

使用独立可执行文件时，数据库会嵌入独立可执行文件内。否则，嵌入的数据库会被复制到输出目录 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";

打包时，所有导入的 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

在打包器中，文件会原样复制到 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`