.html 文件,且不依赖任何外部资源。JavaScript、TypeScript、JSX、CSS、图片、字体、视频、WASM:Bun 会将所有内容内联到一个文件中。
terminal
单文件。随处上传。
输出是一个单独的.html 文件,你可以放到任何地方:
- 上传到 S3 或任何静态文件托管服务——无需维护目录结构,只需一个文件
- 从桌面双击打开——它会在浏览器中打开并离线运行,无需本地主机服务器
- 嵌入到 WebView 中——无需处理相对文件
- 插入
<iframe>中——只需一个文件 URL,即可将交互式内容嵌入另一个页面 - 从任意位置提供服务——任何 HTTP 服务器、CDN 或文件共享服务都可以
node_modules,无需协调构建产物,也无需考虑相对路径。
真正的单文件
通常,分发网页意味着需要管理一个资源文件夹——HTML、JavaScript 包、CSS 文件和图片。单独移动 HTML 文件而不带上其他文件,一切都会出错。浏览器以前也尝试过解决这个问题。Safari 的.webarchive 和 Chrome 的 .mhtml 可以将网页保存为单个文件。实际上,只有部分浏览器能打开它们,这就失去了这样做的意义。
独立 HTML 输出是一个普通的 .html 文件:不是归档文件,也不是文件夹。Bun 使用标准的 <style> 标签、<script> 标签和 data: URI,将每张图片、每种字体以及每一行 CSS 和 JavaScript 都直接嵌入 HTML 中。任何浏览器都能打开它,任何服务器都能托管它。
你可以像分发 PDF 一样分发页面:这是一个可以移动、复制、上传或分享的单一文件,无需担心路径失效或资源缺失。
快速开始
terminal
dist/index.html —— React 应用无需服务器即可运行。
所有内容均内联
Bun 会将 HTML 中找到的每个本地资源都进行内联:任何具有相对路径的文件,无论文件类型是什么,都会嵌入到输出文件中。什么内容会被内联
图片、字体、WASM 二进制文件、视频、音频文件、SVG:Bun 会将相对路径引用的任何文件编码为 base64 格式的
data: URI,并直接嵌入 HTML 中。Bun 会根据文件扩展名检测 MIME 类型。
Bun 会原样保留外部 URL(例如 CDN 链接或绝对 URL)。
与 React 一起使用
React 应用无需额外配置:Bun 会转译 JSX 并解析 npm 包。terminal
terminal
dist/index.html 中。将这一个文件上传到任何地方,它都能正常运行。
与 Tailwind CSS 一起使用
安装插件并在 HTML 或 CSS 中引用 Tailwind:terminal
build.ts
terminal
<style> 标签的形式直接放入 HTML 文件中。
工作原理
当你传入--compile --target=browser 且入口是 HTML 文件时,Bun 会:
- 解析 HTML,发现所有
<script>、<link>、<img>、<video>、<audio>、<source>及其他资源引用 - 将所有 JavaScript/TypeScript/JSX 打包为单个模块
- 将所有 CSS(包括
@import链和 JS 中导入的 CSS)打包成一个样式表 - 将所有相对资源引用转换为 base64 的
data:URI - 将打包后的 JS 以内联
<script type="module">形式放在</body>前 - 将打包后的 CSS 以内联
<style>形式放在<head>内 - 输出一个不依赖任何外部文件的单个
.html文件。
压缩
添加--minify 来压缩 JavaScript 和 CSS:
terminal
build.ts
JavaScript API
使用Bun.build() 以编程方式生成独立的 HTML:
build.ts
outdir 时,输出会以 BuildArtifact 的形式保存在 result.outputs 中:
多个 HTML 文件
你可以传入多个 HTML 文件作为入口,分别生成独立 HTML 文件:terminal
环境变量
使用--env 将环境变量内联到打包的 JavaScript 中:
terminal
process.env.API_URL 的引用替换为字面值。
限制
- 不支持代码拆分——
--splitting不能与--compile --target=browser一起使用 - 大型资源会增加文件大小,因为它们会被编码为 base64(与原始二进制文件相比,体积增加 33%)
- 外部 URL(CDN 链接、绝对 URL)会保持原样:Bun 只内联相对路径