Bun文件檔教程

繁體中文

English
简体中文

繁體中文

English
简体中文

Appearance

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' 導入屬性顯式指定要使用的加載器。

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 文件可以直接導入。

ts
import pkg from "./package.json";
pkg.name; // => "my-package"

在捆綁期間，解析的 JSON 作為 JavaScript 對象內聯到捆綁包中。

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

如果將 .json 文件作為入口點傳遞給打包器，它將轉換為 export default 解析對象的 .js 模塊。

json
{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}
ts
export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

jsonc ​

帶注釋的 JSON 加載器。.jsonc 的默認值。

JSONC（帶注釋的 JSON）文件可以直接導入。Bun 將解析它們，剝離注釋和尾隨逗號。

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

在捆綁期間，解析的 JSONC 作為 JavaScript 對象內聯到捆綁包中，與 json 加載器相同。

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

NOTE

Bun 自動為 `tsconfig.json`、`jsconfig.json`、`package.json` 和 `bun.lock` 文件使用 `jsonc` 加載器。

toml ​

TOML 加載器。.toml 的默認值。

TOML 文件可以直接導入。Bun 將使用其快速原生 TOML 解析器解析它們。

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

// 通過導入屬性：
// import myCustomTOML from './my.config' with {type: "toml"};

在捆綁期間，解析的 TOML 作為 JavaScript 對象內聯到捆綁包中。

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

如果將 .toml 文件作為入口點傳遞，它將轉換為 export default 解析對象的 .js 模塊。

toml
name = "John Doe"
age = 35
email = "johndoe@example.com"
ts
export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

yaml ​

YAML 加載器。.yaml 和 .yml 的默認值。

YAML 文件可以直接導入。Bun 將使用其快速原生 YAML 解析器解析它們。

ts
import config from "./config.yaml";
console.log(config);

// 通過導入屬性：
import data from "./data.txt" with { type: "yaml" };

在捆綁期間，解析的 YAML 作為 JavaScript 對象內聯到捆綁包中。

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

如果將 .yaml 或 .yml 文件作為入口點傳遞，它將轉換為 export default 解析對象的 .js 模塊。

yaml
name: John Doe
age: 35
email: johndoe@example.com
ts
export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

text ​

文本加載器。.txt 的默認值。

文本文件的內容被讀取並作為字符串內聯到捆綁包中。 文本文件可以直接導入。文件被讀取並作為字符串返回。

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

// 要將 html 文件作為文本導入
// "type" 屬性可用於覆蓋默認加載器。
import html from "./index.html" with { type: "text" };

在構建期間引用時，內容作為字符串內聯到捆綁包中。

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

如果將 .txt 文件作為入口點傳遞，它將轉換為 export default 文件內容的 .js 模塊。

txt
Hello, world!
ts
export default "Hello, world!";

napi ​

原生插件加載器。.node 的默認值。

在運行時中，原生插件可以直接導入。

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

在打包器中，.node 文件使用 file 加載器處理。

sqlite ​

SQLite 加載器。with { "type": "sqlite" } 導入屬性

在運行時和打包器中，SQLite 數據庫可以直接導入。這將使用 bun:sqlite 加載數據庫。

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

僅當 target 是 bun 時支持。

默認情況下，數據庫在捆綁包外部（以便你可以使用從其他地方加載的數據庫），因此磁盤上的數據庫文件不會捆綁到最終輸出中。

你可以使用 "embed" 屬性更改此行為：

ts
// 將數據庫嵌入到捆綁包中
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 文件：

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>

它將輸出一個帶有捆綁資源的新 HTML 文件：

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 提取腳本和鏈接標簽作為入口點，以及其他資源作為外部。

目前，選擇器列表是：

  • 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]

NOTE

不同上下文中的 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 一起捆綁。

ts
import "./styles.css";

導入不返回任何值，它僅用於副作用。

sh 加載器 ​

Bun Shell 加載器。.sh 文件的默認值

此加載器用於解析 Bun Shell 腳本。僅在啟動 Bun 本身時支持，因此在打包器或運行時中不可用。

sh
bun run ./script.sh

file ​

文件加載器。所有未識別文件類型的默認值。

文件加載器將導入解析為導入文件的 路徑/URL。它通常用於引用媒體或字體資源。

ts
import logo from "./logo.svg";
console.log(logo);

在運行時中，Bun 檢查 logo.svg 文件是否存在，並將其轉換為磁盤上 logo.svg 位置的絕對路徑。

bash
bun run logo.ts
/path/to/project/logo.svg

在打包器中，情況略有不同。文件按原樣復制到 outdir，導入解析為指向復制文件的相對路徑。

ts
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

NOTE

復制文件的位置和文件名由 [`naming.asset`](/zh-cn/bundler#naming) 的值確定。
此加載器按原樣復制到 `outdir`。復制文件的文件名使用 `naming.asset` 的值確定。

修復 TypeScript 導入錯誤 ​

如果你使用 TypeScript，可能會收到如下錯誤：

ts
// TypeScript 錯誤
// 找不到模塊 './logo.svg' 或其相應的類型聲明。

可以通過在項目的任何位置創建 *.d.ts 文件（任何名稱都有效）來修復，內容如下：

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

這告訴 TypeScript，來自 .svg 的任何默認導入都應視為字符串。

Bun學習網由www.bunjs.com.cn整理維護

MIT Licensed | Copyright © 2023-present