加载器 – Bundler | Bun 文档

Bun 打包器默认实现了一系列开箱即用的加载器。一般来说，打包器和运行时都默认支持相同的文件类型。

.js .cjs .mjs .mts .cts .ts .tsx .jsx .toml .json .txt .wasm .node .html

Bun 使用文件扩展名来确定应该使用哪个内置*加载器*来解析文件。每个加载器都有一个名称，例如 js、tsx 或 json。这些名称在构建插件时使用，这些插件使用自定义加载器扩展 Bun。

您可以使用 'loader' 导入属性显式指定要使用的加载器。

import my_toml from "./my_file" with { loader: "toml" };

内置加载器

`js`

JavaScript。.cjs 和 .mjs 的默认加载器。

解析代码并应用一组默认转换，例如死代码消除和 tree shaking。请注意，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 对象内联到 bundle 中。

var pkg = {
  name: "my-package",
  // ... other fields
};
pkg.name;

如果将 .json 文件作为入口点传递给打包器，它将被转换为一个 .js 模块，该模块 export default 解析后的对象。

输入

输出

输入
{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}

输出
export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com"
}

`toml`

TOML 加载器。.toml 的默认加载器。

TOML 文件可以直接导入。Bun 将使用其快速的原生 TOML 解析器解析它们。

import config from "./bunfig.toml";
config.logLevel; // => "debug"

// via import attribute:
// import myCustomTOML from './my.config' with {type: "toml"};

在打包期间，解析后的 TOML 会作为 JavaScript 对象内联到 bundle 中。

var config = {
  logLevel: "debug",
  // ...other fields
};
config.logLevel;

如果将 .toml 文件作为入口点传递给打包器，它将被转换为一个 .js 模块，该模块 export default 解析后的对象。

输入

输出

输入
name = "John Doe"
age = 35
email = "johndoe@example.com"

输出
export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com"
}

`text`

文本加载器。.txt 的默认加载器。

文本文件的内容被读取并作为字符串内联到 bundle 中。文本文件可以直接导入。该文件被读取并作为字符串返回。

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

// To import an html file as text
// The "type' attribute can be used to override the default loader.
import html from "./index.html" with { type: "text" };

在构建期间被引用时，内容会作为字符串放入 bundle 中。

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

如果将 .txt 文件作为入口点传递，它将被转换为一个 .js 模块，该模块 export default 文件内容。

输入

输出

输入
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:sqlite 加载数据库。

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

仅当 target 为 bun 时才支持。

默认情况下，数据库在 bundle 外部（以便您可以潜在地使用在其他地方加载的数据库），因此磁盘上的数据库文件不会被捆绑到最终输出中。

您可以使用 "embed" 属性更改此行为

// embed the database into the bundle
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:// 开头的内容）

例如，给定此 HTML 文件

src/index.html

src/index.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 文件，其中包含捆绑的资源

dist/output.html

dist/output.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 来提取 script 和 link 标签作为入口点，以及其他资源作为外部资源。

目前，选择器列表如下：

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]

`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，您可能会收到这样的错误

// TypeScript error
// Cannot find module './logo.svg' or its corresponding type declarations.

可以通过在项目的任何位置创建一个 *.d.ts 文件（任何名称都可以），并包含以下内容来解决此问题

declare module "*.svg" {
  const content: string;
  export default content;
}

这告诉 TypeScript，来自 .svg 的任何默认导入都应被视为字符串。