Skip to main content
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' 导入属性显式指定要使用的加载器。 
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 对象。 
var pkg = {
  name: "my-package",
  // ... 其他字段
};
pkg.name;
如果将 .json 文件作为入口点传递给打包器，它将被转换为一个 .js 模块，该模块 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);
在打包期间，解析的 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 文件作为入口点传递，它将被转换为一个 .js 模块，该模块 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" };
在打包期间，解析的 YAML 被内联到包中作为 JavaScript 对象。 
var config = {
  name: "my-app",
  version: "1.0.0",
  // ...其他字段
};
如果将 .yaml 或 .yml 文件作为入口点传递，它将被转换为一个 .js 模块，该模块 export default 解析的对象。 
name: John Doe
age: 35
email: johndoe@example.com

​
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 文件作为入口点传递，它将被转换为一个 .js 模块，该模块 export default 文件内容。 
Hello, world!

​
napi

原生插件加载器。.node 的默认值。 在运行时，原生插件可以直接导入。 
import addon from "./addon.node";
console.log(addon);
在打包器中，.node 文件使用 file 加载器处理。

​
sqlite

SQLite 加载器。with { "type": "sqlite" } 导入属性 在运行时和打包器中，SQLite 数据库可以直接导入。这将使用 bun:sqlite 加载数据库。 
import db from "./my.db" with { type: "sqlite" };
这仅在 target 为 bun 时支持。 默认情况下，数据库在包外部（以便您可以在其他地方加载数据库），因此磁盘上的数据库文件不会被捆绑到最终输出中。 您可以使用 "embed" 属性更改此行为： 
// 将数据库嵌入到包中
import db from "./my.db" with { type: "sqlite", embed: "true" };
使用 独立可执行文件 时，数据库被嵌入到单文件可执行文件中。 否则，要嵌入的数据库会以哈希文件名复制到 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>
它将输出一个包含打包资源的新 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 提取脚本和链接标签作为入口点，以及其他资源作为外部资源。 目前，选择器列表是：
  • audio[src]
  • iframe[src]
  • img[src]
  • img[srcset]
  • link:not([rel~='stylesheet']):not([rel~='modulepreload']):not([rel~='manifest']):not([rel~='icon']):not([rel~='apple-touch-icon'])[href]
  • 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 加载器的行为因使用方式而异：
  1. 静态构建： 当您运行 bun build ./index.html 时，Bun 生成一个包含所有捆绑和哈希资源的静态站点。
  2. 运行时： 当您运行 bun run server.ts（其中 server.ts 导入 HTML 文件）时，Bun 在开发期间动态捆绑资源，启用热模块替换等功能。
  3. 全栈构建： 当您运行 bun build --target=bun server.ts（其中 server.ts 导入 HTML 文件）时，导入解析为 Bun.serve 用于在生产中高效提供预捆绑资源的清单对象。

​
css

CSS 加载器。.css 的默认值。 CSS 文件可以直接导入。这主要用于 全栈应用程序，其中 CSS 与 HTML 一起捆绑。 
import "./styles.css";
导入时没有返回值，仅用于副作用。

​
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 文件是否存在，并将其转换为 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 的值确定。
此加载器被原样复制到 outdir 中。复制文件的名称使用 naming.asset 的值确定。
如果您使用 TypeScript，您可能会遇到如下错误：
// TypeScript 错误
// Cannot find module './logo.svg' or its corresponding type declarations.
这可以通过在项目的任何位置创建 *.d.ts 文件（任何名称都可以）并包含以下内容来修复：
declare module "*.svg" {
  const content: string;
  export default content;
}
这告诉 TypeScript，从 .svg 导入的任何默认导入都应被视为字符串。