归档 - Bun

Bun.Archive 是 Bun 用于 tar 归档的原生 API。它可以从内存数据创建归档、将归档提取到磁盘，以及在不提取的情况下读取归档内容。

快速入门

从文件创建归档：

const archive = new Bun.Archive({
  "hello.txt": "Hello, World!",
  "data.json": JSON.stringify({ foo: "bar" }),
  "nested/file.txt": "嵌套内容",
});

// 写入磁盘
await Bun.write("bundle.tar", archive);

提取归档：

const tarball = await Bun.file("package.tar.gz").bytes();
const archive = new Bun.Archive(tarball);
const entryCount = await archive.extract("./output");
console.log(`提取了 ${entryCount} 个条目`);

不提取读取归档内容：

const tarball = await Bun.file("package.tar.gz").bytes();
const archive = new Bun.Archive(tarball);
const files = await archive.files();

for (const [path, file] of files) {
  console.log(`${path}: ${await file.text()}`);
}

创建归档

使用 new Bun.Archive() 从对象创建归档，其中键是文件路径，值是文件内容。默认情况下，归档是未压缩的：

// 创建未压缩的 tar 归档（默认）
const archive = new Bun.Archive({
  "README.md": "# 我的项目",
  "src/index.ts": "console.log('Hello');",
  "package.json": JSON.stringify({ name: "my-project" }),
});

文件内容可以是：

字符串 - 文本内容
Blob - 二进制数据
ArrayBufferView（如 Uint8Array）- 原始字节
ArrayBuffer - 原始二进制数据

const data = "binary data";
const arrayBuffer = new ArrayBuffer(8);

const archive = new Bun.Archive({
  "text.txt": "纯文本",
  "blob.bin": new Blob([data]),
  "bytes.bin": new Uint8Array([1, 2, 3, 4]),
  "buffer.bin": arrayBuffer,
});

将归档写入磁盘

使用 Bun.write() 将归档写入磁盘：

// 写入未压缩的 tar（默认）
const archive = new Bun.Archive({
  "file1.txt": "content1",
  "file2.txt": "content2",
});
await Bun.write("output.tar", archive);

// 写入 gzip 压缩的 tar
const compressed = new Bun.Archive({ "src/index.ts": "console.log('Hello');" }, { compress: "gzip" });
await Bun.write("output.tar.gz", compressed);

获取归档字节

以字节或 Blob 形式获取归档数据：

const archive = new Bun.Archive({ "hello.txt": "Hello, World!" });

// 作为 Uint8Array
const bytes = await archive.bytes();

// 作为 Blob
const blob = await archive.blob();

// 带 gzip 压缩（在构造时设置）
const gzipped = new Bun.Archive({ "hello.txt": "Hello, World!" }, { compress: "gzip" });
const gzippedBytes = await gzipped.bytes();
const gzippedBlob = await gzipped.blob();

提取归档

从现有归档数据

从现有的 tar/tar.gz 数据创建归档：

// 从文件
const tarball = await Bun.file("package.tar.gz").bytes();
const archiveFromFile = new Bun.Archive(tarball);

// 从 fetch 响应
const response = await fetch("https://example.com/archive.tar.gz");
const archiveFromFetch = new Bun.Archive(await response.blob());

提取到磁盘

使用 .extract() 将所有文件写入目录：

const tarball = await Bun.file("package.tar.gz").bytes();
const archive = new Bun.Archive(tarball);
const count = await archive.extract("./extracted");
console.log(`提取了 ${count} 个条目`);

extract() 会创建目标目录（如果不存在），并覆盖现有文件。返回的计数包括文件、目录和符号链接（在 POSIX 系统上）。注意：在 Windows 上，Bun 在提取时始终跳过符号链接，无论权限级别如何。在 Linux 和 macOS 上，符号链接正常提取。 安全说明：Bun.Archive 在提取过程中验证路径。它会拒绝绝对路径（POSIX /、Windows 驱动器号如 C:\ 或 C:/，以及 UNC 路径如 \\server\share）和不安全的符号链接目标。路径遍历组件（..）会被规范化移除，以防止目录逃逸攻击：dir/sub/../file 变为 dir/file。

过滤提取的文件

使用 glob 模式仅提取特定文件。模式会与使用正斜杠（/）规范化的归档条目路径进行匹配。正向模式指定要包含的内容，负向模式（以 ! 为前缀）指定要排除的内容。当只提供负向模式时，所有不匹配它们的条目都会被包含：

const tarball = await Bun.file("package.tar.gz").bytes();
const archive = new Bun.Archive(tarball);

// 仅提取 TypeScript 文件
const tsCount = await archive.extract("./extracted", { glob: "**/*.ts" });

// 从多个目录提取文件
const multiCount = await archive.extract("./extracted", {
  glob: ["src/**", "lib/**"],
});

当混合使用正向和负向模式时，条目必须匹配至少一个正向模式且不匹配任何负向模式：

// 提取除了 node_modules 之外的所有内容
const distCount = await archive.extract("./extracted", {
  glob: ["**", "!node_modules/**"],
});

// 提取源文件但排除测试
const srcCount = await archive.extract("./extracted", {
  glob: ["src/**", "!**/*.test.ts", "!**/__tests__/**"],
});

读取归档内容

获取所有文件

使用 .files() 以 File 对象的 Map 形式获取归档内容，而无需提取到磁盘。与处理所有条目类型的 extract() 不同，files() 只返回常规文件（不包括目录）：

const tarball = await Bun.file("package.tar.gz").bytes();
const archive = new Bun.Archive(tarball);
const files = await archive.files();

for (const [path, file] of files) {
  console.log(`${path}: ${file.size} 字节`);
  console.log(await file.text());
}

每个 File 对象包含：

name - 归档内的文件路径（始终使用正斜杠 / 作为分隔符）
size - 文件大小（字节）
lastModified - 修改时间戳
标准 Blob 方法，如 text()、arrayBuffer() 和 stream()

注意：files() 会将文件内容加载到内存中。对于大型归档，请使用 extract() 直接写入磁盘。

错误处理

归档操作可能因数据损坏、I/O 错误或无效路径而失败。使用 try/catch 处理这些情况：

try {
  const tarball = await Bun.file("package.tar.gz").bytes();
  const archive = new Bun.Archive(tarball);
  const count = await archive.extract("./output");
  console.log(`提取了 ${count} 个条目`);
} catch (e: unknown) {
  if (e instanceof Error) {
    const error = e as Error & { code?: string };
    if (error.code === "EACCES") {
      console.error("权限被拒绝");
    } else if (error.code === "ENOSPC") {
      console.error("磁盘空间不足");
    } else {
      console.error("归档错误:", error.message);
    }
  } else {
    console.error("归档错误:", String(e));
  }
}

常见错误场景：

损坏/截断的归档 - new Archive() 会加载归档数据；错误可能会延迟到读取/提取操作时
权限被拒绝 - 如果目标目录不可写，extract() 会抛出异常
磁盘空间不足 - 如果没有足够空间，extract() 会抛出异常
无效路径 - 对于格式错误的文件路径，操作会抛出异常

对于不可信归档的额外安全性，你可以在提取前枚举和验证路径：

const archive = new Bun.Archive(untrustedData);
const files = await archive.files();

// 可选：用于额外检查的自定义验证
for (const [path] of files) {
  // 示例：拒绝隐藏文件
  if (path.startsWith(".") || path.includes("/.")) {
    throw new Error(`隐藏文件被拒绝: ${path}`);
  }
  // 示例：白名单特定目录
  if (!path.startsWith("src/") && !path.startsWith("lib/")) {
    throw new Error(`意外的路径: ${path}`);
  }
}

// 提取到受控的目标目录
await archive.extract("./safe-output");

当使用 glob 模式调用时，如果没有匹配的文件，files() 会返回空的 Map：

const matches = await archive.files("*.nonexistent");
if (matches.size === 0) {
  console.log("未找到匹配的文件");
}

使用 Glob 模式过滤

传递 glob 模式以过滤返回哪些文件：

// 仅获取 TypeScript 文件
const tsFiles = await archive.files("**/*.ts");

// 获取 src 目录中的文件
const srcFiles = await archive.files("src/*");

// 获取所有 JSON 文件（递归）
const jsonFiles = await archive.files("**/*.json");

// 使用模式数组获取多种文件类型
const codeFiles = await archive.files(["**/*.ts", "**/*.js"]);

支持的 glob 模式（Bun.Glob 语法的子集）：

* - 匹配除 / 以外的任意字符
** - 匹配包括 / 在内的任意字符
? - 匹配单个字符
[abc] - 匹配字符集合
{a,b} - 匹配备选方案
!pattern - 排除匹配模式的文件（否定）。当只提供否定模式时，所有不匹配它们的文件都会被包含。

完整的 glob 语法（包括转义和高级模式），请参见 Bun.Glob。

压缩

默认情况下，Bun.Archive 创建未压缩的 tar 归档。使用 { compress: "gzip" } 启用 gzip 压缩：

// 默认：未压缩的 tar
const archive = new Bun.Archive({ "hello.txt": "Hello, World!" });

// 读取：自动检测 gzip
const gzippedTarball = await Bun.file("archive.tar.gz").bytes();
const readArchive = new Bun.Archive(gzippedTarball);

// 启用 gzip 压缩
const compressed = new Bun.Archive({ "hello.txt": "Hello, World!" }, { compress: "gzip" });

// 自定义压缩级别 (1-12) 的 gzip
const maxCompression = new Bun.Archive({ "hello.txt": "Hello, World!" }, { compress: "gzip", level: 12 });

options 参数接受：

无选项或 undefined - 未压缩的 tar（默认）
{ compress: "gzip" } - 在级别 6 启用 gzip 压缩
{ compress: "gzip", level: number } - 使用自定义级别 1-12 的 gzip（1 = 最快，12 = 最小）

示例

打包项目文件

import { Glob } from "bun";

// 收集源文件
const files: Record<string, string> = {};
const glob = new Glob("src/**/*.ts");

for await (const path of glob.scan(".")) {
  // 将路径分隔符规范化为正斜杠，以实现跨平台兼容性
  const archivePath = path.replaceAll("\\", "/");
  files[archivePath] = await Bun.file(path).text();
}

// 添加 package.json
files["package.json"] = await Bun.file("package.json").text();

// 创建压缩归档并写入磁盘
const archive = new Bun.Archive(files, { compress: "gzip" });
await Bun.write("bundle.tar.gz", archive);

提取并处理 npm 包

const response = await fetch("https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz");
const archive = new Bun.Archive(await response.blob());

// 获取 package.json
const files = await archive.files("package/package.json");
const packageJson = files.get("package/package.json");

if (packageJson) {
  const pkg = JSON.parse(await packageJson.text());
  console.log(`包: ${pkg.name}@${pkg.version}`);
}

从目录创建归档

import { readdir } from "node:fs/promises";
import { join } from "node:path";

async function archiveDirectory(dir: string, compress = false): Promise<Bun.Archive> {
  const files: Record<string, Blob> = {};

  async function walk(currentDir: string, prefix: string = "") {
    const entries = await readdir(currentDir, { withFileTypes: true });

    for (const entry of entries) {
      const fullPath = join(currentDir, entry.name);
      const archivePath = prefix ? `${prefix}/${entry.name}` : entry.name;

      if (entry.isDirectory()) {
        await walk(fullPath, archivePath);
      } else {
        files[archivePath] = Bun.file(fullPath);
      }
    }
  }

  await walk(dir);
  return new Bun.Archive(files, compress ? { compress: "gzip" } : undefined);
}

const archive = await archiveDirectory("./my-project", true);
await Bun.write("my-project.tar.gz", archive);

参考

注意：以下类型签名已简化。完整的类型定义请参见 packages/bun-types/bun.d.ts。

type ArchiveInput =
  | Record<string, string | Blob | Bun.ArrayBufferView | ArrayBufferLike>
  | Blob
  | Bun.ArrayBufferView
  | ArrayBufferLike;

type ArchiveOptions = {
  /** 压缩算法。目前仅支持 "gzip"。 */
  compress?: "gzip";
  /** 压缩级别 1-12（启用 gzip 时默认为 6）。 */
  level?: number;
};

interface ArchiveExtractOptions {
  /** 用于过滤提取的 Glob 模式。支持以 "!" 为前缀的否定模式。 */
  glob?: string | readonly string[];
}

class Archive {
  /**
   * 从输入数据创建 Archive
   * @param data - 要归档的文件（作为对象）或现有的归档数据（作为字节/blob）
   * @param options - 压缩选项。默认为未压缩。
   *                  传递 { compress: "gzip" } 以启用压缩。
   */
  constructor(data: ArchiveInput, options?: ArchiveOptions);

  /**
   * 将归档提取到目录
   * @returns 提取的条目数（文件、目录和符号链接）
   */
  extract(path: string, options?: ArchiveExtractOptions): Promise<number>;

  /**
   * 获取 Blob 格式的归档（使用构造函数中的压缩设置）
   */
  blob(): Promise<Blob>;

  /**
   * 获取 Uint8Array 格式的归档（使用构造函数中的压缩设置）
   */
  bytes(): Promise<Uint8Array<ArrayBuffer>>;

  /**
   * 获取归档内容为 File 对象（仅常规文件，不含目录）
   */
  files(glob?: string | readonly string[]): Promise<Map<string, File>>;
}

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

归档

快速入门

创建归档

将归档写入磁盘

获取归档字节

提取归档

从现有归档数据

提取到磁盘

过滤提取的文件

读取归档内容

获取所有文件

错误处理

使用 Glob 模式过滤

压缩

示例

打包项目文件

提取并处理 npm 包

从目录创建归档

参考

​快速入门

​创建归档

​将归档写入磁盘

​获取归档字节

​提取归档

​从现有归档数据

​提取到磁盘

​过滤提取的文件

​读取归档内容

​获取所有文件

​错误处理

​使用 Glob 模式过滤

​压缩

​示例

​打包项目文件

​提取并处理 npm 包

​从目录创建归档

​参考

快速入门

创建归档

将归档写入磁盘

获取归档字节

提取归档

从现有归档数据

提取到磁盘

过滤提取的文件

读取归档内容

获取所有文件

错误处理

使用 Glob 模式过滤

压缩

示例

打包项目文件

提取并处理 npm 包

从目录创建归档

参考