archiver

隆重推出 Archiver 4.0 - 一个跨平台、多格式的归档工具和 Go 库。这个通用的替代品集强大灵活的库和优雅的命令行界面于一体，可以替代多个特定平台或特定格式的归档工具。

:警告: v4 版本目前处于 Alpha 阶段。核心库 API 运行良好，但命令行工具尚未实现，大部分自动化测试也尚未完成。如果你需要使用 arc 命令，目前请继续使用 v3 版本。

特性

• 面向流的 API
• 自动识别归档和压缩格式：
  • 通过文件名
  • 通过文件头
• 统一遍历目录、归档文件和任何其他文件，作为 io/fs 文件系统：
  • DirFS
  • FileFS
  • ArchiveFS
• 压缩和解压缩文件
• 创建和提取归档文件
• 遍历归档文件
• 从归档中仅提取特定文件
• 插入（附加）到 .tar 和 .zip 归档
• 读取受密码保护的 7-Zip 文件
• 支持多种归档和压缩格式
• 可扩展（通过注册即可添加更多格式）
• 跨平台，静态二进制文件
• 纯 Go 实现（无 cgo）
• 多线程 Gzip
• 可调节压缩级别
• 自动将压缩文件添加到 zip 归档而无需重新压缩
• 打开受密码保护的 RAR 归档

支持的压缩格式

• brotli (.br)
• bzip2 (.bz2)
• flate (.zip)
• gzip (.gz)
• lz4 (.lz4)
• lzip (.lz)
• snappy (.sz)
• xz (.xz)
• zlib (.zz)
• zstandard (.zst)

支持的归档格式

• .zip
• .tar（包括任何压缩变体，如 .tar.gz）
• .rar（仅读取）
• .7z（仅读取）

Tar 文件可以选择使用任何压缩格式进行压缩。

命令行使用

v4 版本即将推出。请参阅 v3 最新文档。

库使用

$ go get github.com/mholt/archiver/v4

创建归档

创建归档可以完全不需要实际的磁盘或存储设备，因为你只需要传入一个 File 结构体 列表即可。

然而，从磁盘文件创建归档是很常见的，所以你可以使用 FilesFromDisk() 函数 来帮助你将磁盘上的文件名映射到归档中的路径。然后创建并自定义格式类型。

在这个例子中，我们将 4 个文件和一个目录（包括其内容，递归）添加到一个 .tar.gz 文件中：

// 将磁盘上的文件映射到归档中的路径
files, err := archiver.FilesFromDisk(nil, map[string]string{
	"/path/on/disk/file1.txt": "file1.txt",
	"/path/on/disk/file2.txt": "subfolder/file2.txt",
	"/path/on/disk/file3.txt": "",              // 放在归档根目录，名为 file3.txt
	"/path/on/disk/file4.txt": "subfolder/",    // 放在 subfolder 中，名为 file4.txt
	"/path/on/disk/folder":    "Custom Folder", // 递归添加内容
})
if err != nil {
	return err
}

// 创建我们将写入的输出文件
out, err := os.Create("example.tar.gz")
if err != nil {
	return err
}
defer out.Close()

// 我们可以使用 CompressedArchive 类型来 gzip 一个 tarball
// （压缩不是必需的；你可以直接使用 Tar）
format := archiver.CompressedArchive{
	Compression: archiver.Gz{},
	Archival:    archiver.Tar{},
}

// 创建归档
err = format.Archive(context.Background(), out, files)
if err != nil {
	return err
}

FilesFromDisk() 的第一个参数是一个可选的选项结构体，允许你自定义如何添加文件。

提取归档

提取归档、从归档中提取文件以及遍历归档都是同一个函数。

只需使用你的格式类型（例如 Zip）来调用 Extract()。你需要传入一个上下文（用于取消），输入流，你想从归档中提取的文件列表，以及一个处理每个文件的回调函数。

如果你想要所有文件，传入一个 nil 文件路径列表。

// 用于读取输入流的类型
format := archiver.Zip{}

// 我们想从归档中提取的文件列表；任何
// 目录都将包括其所有内容，除非
// 我们从处理程序返回 fs.SkipDir
// （将此设为 nil 以遍历归档中的所有文件）
fileList := []string{"file1.txt", "subfolder"}

handler := func(ctx context.Context, f archiver.File) error {
	// 处理文件
	return nil
}

err := format.Extract(ctx, input, fileList, handler)
if err != nil {
	return err
}

识别格式

有一个内容未知的输入流？没问题，archiver 可以为你识别它。它会尝试基于文件名和/或文件头（会窥视流）进行匹配：

format, input, err := archiver.Identify("filename.tar.zst", input)
if err != nil {
	return err
}
// 现在你可以将 format 类型断言为你需要的类型；
// 确保使用返回的流重新读取在 Identify() 期间消耗的字节

// 想要提取某些内容？
if ex, ok := format.(archiver.Extractor); ok {
	// ... 继续提取
}

// 或者也许它是压缩的，你想要解压缩？
if decom, ok := format.(archiver.Decompressor); ok {
	rc, err := decom.OpenReader(unknownFile)
	if err != nil {
		return err
	}
	defer rc.Close()

	// 从 rc 读取以获取解压缩的数据
}

Identify() 通过从流的开始读取任意数量的字节（恰好足以检查文件头）来工作。它会缓冲这些字节并返回一个新的读取器，让你可以重新读取它们。

虚拟文件系统

这是我最喜欢的功能。

假设你有一个文件。它可能是磁盘上的一个真实目录、一个归档文件、一个压缩归档文件，或者任何其他常规文件。你并不真的关心它是什么；你只是想无论它是什么都能统一使用它。

使用 archiver 简单地创建一个文件系统：

// filename 可能是：
// - 一个文件夹 ("/home/you/Desktop")
// - 一个归档文件 ("example.zip")
// - 一个压缩归档文件 ("example.tar.gz")
// - 一个常规文件 ("example.txt")
// - 一个压缩的常规文件 ("example.txt.gz")
fsys, err := archiver.FileSystem(filename)
if err != nil {
	return err
}

这是一个功能齐全的 fs.FS，所以你可以打开文件和读取目录，无论输入是什么类型的文件。

例如，要打开一个特定的文件：

f, err := fsys.Open("file")
if err != nil {
	return err
}
defer f.Close()

如果你打开了一个常规文件，你可以从中读取。如果是压缩文件，读取时会自动解压缩。

如果你打开了一个目录，你可以列出其内容：

if dir, ok := f.(fs.ReadDirFile); ok {
	// 0 获取所有条目，但你可以传入 > 0 来分页
	entries, err := dir.ReadDir(0)
	if err != nil {
		return err
	}
	for _, e := range entries {
		fmt.Println(e.Name())
	}
}

或者这样获取目录列表：

entries, err := fsys.ReadDir("Playlists")
if err != nil {
	return err
}
for _, e := range entries {
	fmt.Println(e.Name())
}

或者你可能想遍历文件系统的全部或部分，但跳过名为 .git 的文件夹：

err := fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
	if err != nil {
		return err
	}
	if path == ".git" {
		return fs.SkipDir
	}
	fmt.Println("Walking:", path, "Dir?", d.IsDir())
	return nil
})
if err != nil {
	return err
}

与 http.FileServer 一起使用

它可以与 http.FileServer 一起使用，在浏览器中浏览归档文件和目录。但是，由于 http.FileServer 的工作方式，不要直接将 http.FileServer 用于压缩文件；而是像下面这样包装它：

fileServer := http.FileServer(http.FS(archiveFS))
http.HandleFunc("/", func(writer http.ResponseWriter, request *http.Request) {
	// 禁用范围请求
	writer.Header().Set("Accept-Ranges", "none")
	request.Header.Del("Range")
	
	// 禁用内容类型嗅探
	ctype := mime.TypeByExtension(filepath.Ext(request.URL.Path))
	writer.Header()["Content-Type"] = nil
	if ctype != "" {
		writer.Header().Set("Content-Type", ctype)
	}
	fileServer.ServeHTTP(writer, request)
})

如果无法从文件名推断内容类型，http.FileServer 默认会尝试嗅探 Content-Type。为此，http 包会尝试从文件读取，然后再 Seek 回文件开头，这是库目前无法实现的。对范围请求也是如此。由于依赖项的限制，archiver 目前不支持在归档文件中进行 Seek 操作。

如果需要内容类型，你可以自己注册它。

压缩数据

压缩格式让你可以打开写入器来压缩数据：

// 包装底层写入器 w
compressor, err := archiver.Zstd{}.OpenWriter(w)
if err != nil {
	return err
}
defer compressor.Close()

// 写入 compressor 的数据将被压缩

解压数据

同样，压缩格式让你可以打开读取器来解压数据：

// 包装底层读取器 r
decompressor, err := archiver.Brotli{}.OpenReader(r)
if err != nil {
	return err
}
defer decompressor.Close()

// 从 decompressor 读取的数据将被解压

向 tarball 和 zip 归档文件追加内容

通过在 tar 或 zip 流上调用 Insert()，可以在不创建全新归档的情况下向 Tar 和 Zip 归档文件追加内容。但是，对于 tarball，这要求 tarball 不被压缩（由于修改压缩字典的复杂性）。

以下是一个向磁盘上的 tarball 追加文件的例子：

tarball, err := os.OpenFile("example.tar", os.O_RDWR, 0644)
if err != nil {
	return err
}
defer tarball.Close()

// 为归档的根目录准备一个文本文件
files, err := archiver.FilesFromDisk(nil, map[string]string{
	"/home/you/lastminute.txt": "",
})

err := archiver.Tar{}.Insert(context.Background(), tarball, files)
if err != nil {
	return err
}

向 Zip 归档文件插入内容的代码类似，只是你需要在 Zip 类型上调用 Insert() 而不是 Tar。