package zip

import "archive/zip"

zip 包提供对 ZIP 归档文件的读写支持。

详情参见 [ZIP 规范]。

本包不支持磁盘跨卷存储。

关于 ZIP64 的说明:

为保持向后兼容,FileHeader 同时包含 32 位和 64 位大小字段。 64 位字段始终存储正确数值,普通归档文件中两类字段值一致。 对于需要使用 ZIP64 格式的文件,32 位字段会设为 0xffffffff,此时必须使用 64 位字段。

Index

Examples

Constants

const (
	Store   uint16 = 0 // 无压缩
	Deflate uint16 = 8 // DEFLATE 压缩
)

压缩方法

Variables

var (
	ErrFormat       = errors.New("zip: not a valid zip file")
	ErrAlgorithm    = errors.New("zip: unsupported compression algorithm")
	ErrChecksum     = errors.New("zip: checksum error")
	ErrInsecurePath = errors.New("zip: insecure file path")
)

Functions

func RegisterCompressor

func RegisterCompressor(method uint16, comp Compressor)

RegisterCompressor 为指定的方法 ID 注册自定义压缩器。 常见方法 Store 和 Deflate 已内置。

func RegisterDecompressor

func RegisterDecompressor(method uint16, dcomp Decompressor)

RegisterDecompressor 允许为指定的方法 ID 自定义解压器。 常见方法 Store 和 Deflate 已内置。

Types

type Compressor

type Compressor func(w io.Writer) (io.WriteCloser, error)

Compressor 返回一个新的压缩写入器,向 w 写入数据。 必须调用 WriteCloser 的 Close 方法将待写入的数据刷新到 w。 Compressor 本身必须可以安全地被多个 goroutine 同时调用, 但每个返回的写入器同一时间只会被一个 goroutine 使用。

type Decompressor

type Decompressor func(r io.Reader) io.ReadCloser

Decompressor 返回一个新的解压读取器,从 r 读取数据。 必须调用 io.ReadCloser 的 Close 方法来释放相关资源。 Decompressor 本身必须可以安全地被多个 goroutine 同时调用, 但每个返回的读取器同一时间只会被一个 goroutine 使用。

type File

type File struct {
	FileHeader
	// contains filtered or unexported fields
}

File 是 ZIP 归档中的单个文件。 文件信息位于内嵌的 FileHeader 中。 可通过调用 File.Open 访问文件内容。

func (*File) DataOffset
func (f *File) DataOffset() (offset int64, err error)

DataOffset 返回文件的可能已压缩数据的偏移量, 相对于 zip 文件的开头。

大多数调用者应改用 File.Open,它会透明地 解压数据并校验校验和。

func (*File) Open
func (f *File) Open() (io.ReadCloser, error)

Open 返回一个 ReadCloser,提供对 File 内容的访问。 可以并发读取多个文件。

func (*File) OpenRaw
func (f *File) OpenRaw() (io.Reader, error)

OpenRaw 返回一个 Reader,提供对 File 内容的访问而 不进行解压。

type FileHeader

type FileHeader struct {
	// Name 为文件名称
	//
	// 必须为相对路径,不能以盘符(如 C:)开头,
	// 且必须使用正斜杠而非反斜杠。末尾带斜杠表示该条目为目录,不应包含数据
	Name string

	// Comment 为任意用户自定义字符串,长度小于 64KiB
	Comment string

	// NonUTF8 标识 Name 和 Comment 未使用 UTF-8 编码
	//
	// 按规范,唯一允许的其他编码应为 CP-437,
	// 但历史上很多 ZIP 读取器会将 Name 和 Comment 按系统本地字符编码解析
	//
	// 仅当用户需要为特定本地化区域生成非可移植 ZIP 文件时,才应设置该标志。
	// 其他情况下,Writer 会为合法 UTF-8 字符串自动设置 ZIP 格式的 UTF-8 标志
	NonUTF8 bool

	CreatorVersion uint16
	ReaderVersion  uint16
	Flags          uint16

	// Method 为压缩方法,为 0 时使用 Store(无压缩)
	Method uint16

	// Modified 为文件的修改时间
	//
	// 读取时,优先使用扩展时间戳而非旧版 MS-DOS 日期字段,
	// 时间差值会作为时区偏移。若仅存在 MS-DOS 日期,则时区默认为 UTC
	//
	// 写入时,始终生成与时区无关的扩展时间戳。
	// 旧版 MS-DOS 日期字段会按 Modified 时间的所在时区编码
	Modified time.Time

	// ModifiedTime 为 MS-DOS 编码格式的时间
	//
	// 已弃用:请改用 Modified
	ModifiedTime uint16

	// ModifiedDate 为 MS-DOS 编码格式的日期
	//
	// 已弃用:请改用 Modified
	ModifiedDate uint16

	// CRC32 为文件内容的 CRC32 校验和
	CRC32 uint32

	// CompressedSize 为文件压缩后的字节大小
	// 若文件压缩前/压缩后大小超出 32 位范围,该字段会设为 ^uint32(0)
	//
	// 已弃用:请改用 CompressedSize64
	CompressedSize uint32

	// UncompressedSize 为文件未压缩的字节大小
	// 若文件压缩前/压缩后大小超出 32 位范围,该字段会设为 ^uint32(0)
	//
	// 已弃用:请改用 UncompressedSize64
	UncompressedSize uint32

	// CompressedSize64 为文件压缩后的字节大小
	CompressedSize64 uint64

	// UncompressedSize64 为文件未压缩的字节大小
	UncompressedSize64 uint64

	Extra         []byte
	ExternalAttrs uint32 // 含义取决于 CreatorVersion
}

FileHeader 描述 ZIP 文件中的单个文件条目 详情参见 [ZIP 规范]

func FileInfoHeader
func FileInfoHeader(fi fs.FileInfo) (*FileHeader, error)

FileInfoHeader 从 fs.FileInfo 创建一个部分填充的 FileHeader 由于 fs.FileInfo 的 Name 方法仅返回文件的基础名称, 可能需要修改返回头部的 Name 字段以设置文件完整路径 若需要压缩,调用方应设置 FileHeader.Method 字段,该字段默认为空

func (*FileHeader) FileInfo
func (h *FileHeader) FileInfo() fs.FileInfo

FileInfo 返回该 FileHeader 对应的 fs.FileInfo

func (*FileHeader) ModTime
func (h *FileHeader) ModTime() time.Time

ModTime 通过旧版 ModifiedDate 和 ModifiedTime 字段返回 UTC 格式的修改时间

已弃用:请改用 Modified

func (*FileHeader) Mode
func (h *FileHeader) Mode() (mode fs.FileMode)

Mode 返回 FileHeader 的权限与模式位

func (*FileHeader) SetModTime
func (h *FileHeader) SetModTime(t time.Time)

SetModTime 将 Modified、ModifiedTime 和 ModifiedDate 字段设置为给定的 UTC 时间

已弃用:请改用 Modified

func (*FileHeader) SetMode
func (h *FileHeader) SetMode(mode fs.FileMode)

SetMode 修改 FileHeader 的权限与模式位

type ReadCloser

type ReadCloser struct {
	Reader
	// contains filtered or unexported fields
}

ReadCloser 是一个 Reader,在不再需要时必须关闭。

func OpenReader
func OpenReader(name string) (*ReadCloser, error)

OpenReader 将打开由 name 指定的 Zip 文件并返回一个 ReadCloser。

如果归档中的任何文件使用了非本地名称 (如 filepath.IsLocal 所定义)或包含反斜杠的名称, 并且 GODEBUG 环境变量包含 `zipinsecurepath=0`, OpenReader 会返回带有 ErrInsecurePath 错误的 reader。 Go 的未来版本可能会默认引入此行为。 希望接受非本地名称的程序可以忽略 ErrInsecurePath 错误并使用返回的 reader。

func (*ReadCloser) Close
func (rc *ReadCloser) Close() error

Close 关闭 Zip 文件,使其无法用于 I/O。

type Reader

type Reader struct {
	File    []*File
	Comment string
	// contains filtered or unexported fields
}

Reader 从 ZIP 归档中提供内容。

Example
package main

import (
	"archive/zip"
	"fmt"
	"io"
	"log"
	"os"
)

func main() {
	// Open a zip archive for reading.
	r, err := zip.OpenReader("testdata/readme.zip")
	if err != nil {
		log.Fatal(err)
	}
	defer r.Close()

	// Iterate through the files in the archive,
	// printing some of their contents.
	for _, f := range r.File {
		fmt.Printf("Contents of %s:\n", f.Name)
		rc, err := f.Open()
		if err != nil {
			log.Fatal(err)
		}
		_, err = io.CopyN(os.Stdout, rc, 68)
		if err != nil {
			log.Fatal(err)
		}
		rc.Close()
		fmt.Println()
	}
}

Output:

Contents of README:
This is the source code repository for the Go programming language.
func NewReader
func NewReader(r io.ReaderAt, size int64) (*Reader, error)

NewReader 返回一个新的 Reader,从 r 读取,假定其 具有给定的字节大小。

如果归档中的任何文件使用了非本地名称 (如 filepath.IsLocal 所定义)或包含反斜杠的名称, 并且 GODEBUG 环境变量包含 `zipinsecurepath=0`, NewReader 会返回带有 ErrInsecurePath 错误的 reader。 Go 的未来版本可能会默认引入此行为。 希望接受非本地名称的程序可以忽略 ErrInsecurePath 错误并使用返回的 reader。

func (*Reader) Open
func (r *Reader) Open(name string) (fs.File, error)

Open 使用 fs.FS.Open 的语义打开 ZIP 归档中 指定名称的文件: 路径始终以斜杠分隔,没有 开头的 / 或 ../ 元素。

func (*Reader) RegisterDecompressor
func (r *Reader) RegisterDecompressor(method uint16, dcomp Decompressor)

RegisterDecompressor 为特定的方法 ID 注册或覆盖自定义解压器。 如果找不到给定方法的解压器, Reader 将默认在包级别查找解压器。

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer 实现了一个 zip 文件写入器。

Example
package main

import (
	"archive/zip"
	"bytes"
	"log"
)

func main() {
	// Create a buffer to write our archive to.
	buf := new(bytes.Buffer)

	// Create a new zip archive.
	w := zip.NewWriter(buf)

	// Add some files to the archive.
	var files = []struct {
		Name, Body string
	}{
		{"readme.txt", "This archive contains some text files."},
		{"gopher.txt", "Gopher names:\nGeorge\nGeoffrey\nGonzo"},
		{"todo.txt", "Get animal handling licence.\nWrite more examples."},
	}
	for _, file := range files {
		f, err := w.Create(file.Name)
		if err != nil {
			log.Fatal(err)
		}
		_, err = f.Write([]byte(file.Body))
		if err != nil {
			log.Fatal(err)
		}
	}

	// Make sure to check the error on Close.
	err := w.Close()
	if err != nil {
		log.Fatal(err)
	}
}
func NewWriter
func NewWriter(w io.Writer) *Writer

NewWriter 返回一个新的 Writer,将 zip 文件写入 w。

func (*Writer) AddFS
func (w *Writer) AddFS(fsys fs.FS) error

AddFS 将 fs.FS 中的文件添加到归档。 它从文件系统根目录开始遍历目录树, 使用 deflate 将每个文件添加到 zip,同时保持目录结构。

func (*Writer) Close
func (w *Writer) Close() error

Close 通过写入中央目录来完成 zip 文件的写入。 它不会关闭底层写入器。

func (*Writer) Copy
func (w *Writer) Copy(f *File) error

Copy 将文件 f(从 Reader 获取)复制到 w 中。它直接复制原始 形式,绕过解压、压缩和校验。

func (*Writer) Create
func (w *Writer) Create(name string) (io.Writer, error)

Create 使用提供的名称向 zip 文件添加一个文件。 它返回一个 Writer,应将文件内容写入该写入器。 文件内容将使用 Deflate 方法压缩。 名称必须是相对路径:它不能以盘符(例如 C:)或前导斜杠开头, 并且只允许使用正斜杠。要创建目录而不是文件,请在名称末尾 添加斜杠。重复的名称不会覆盖之前的条目,而是追加到 zip 文件中。 文件内容必须在下一次调用 Writer.Create、Writer.CreateHeader 或 Writer.Close 之前写入该 io.Writer。

func (*Writer) CreateHeader
func (w *Writer) CreateHeader(fh *FileHeader) (io.Writer, error)

CreateHeader 使用提供的 FileHeader 作为文件元数据向 zip 归档添加一个文件。 Writer 取得 fh 的所有权,并可能修改其字段。 调用方在调用 Writer.CreateHeader 之后不得修改 fh。

这返回一个 Writer,应将文件内容写入该写入器。 文件内容必须在下一次调用 Writer.Create、Writer.CreateHeader、 Writer.CreateRaw 或 Writer.Close 之前写入该 io.Writer。

func (*Writer) CreateRaw
func (w *Writer) CreateRaw(fh *FileHeader) (io.Writer, error)

CreateRaw 使用提供的 FileHeader 向 zip 归档添加一个文件,并 返回一个 Writer,应将文件内容写入该写入器。文件内容必须在 下一次调用 Writer.Create、Writer.CreateHeader、Writer.CreateRaw 或 Writer.Close 之前写入该 io.Writer。

与 Writer.CreateHeader 不同,传递给 Writer 的字节不会被压缩。

CreateRaw 的参数存储在 w 中。如果该参数是指向从内存数据创建的 Reader 所获取的 File 中内嵌 FileHeader 的指针, 那么 w 将引用该内存的全部内容。

func (*Writer) Flush
func (w *Writer) Flush() error

Flush 将所有缓冲数据刷新到底层写入器。 通常不需要调用 Flush;调用 Close 就足够了。

func (*Writer) RegisterCompressor
func (w *Writer) RegisterCompressor(method uint16, comp Compressor)

RegisterCompressor 为特定的方法 ID 注册或覆盖自定义压缩器。 如果找不到给定方法的压缩器,Writer 将默认 在包级别查找压缩器。

Example
package main

import (
	"archive/zip"
	"bytes"
	"compress/flate"
	"io"
)

func main() {
	// Override the default Deflate compressor with a higher compression level.

	// Create a buffer to write our archive to.
	buf := new(bytes.Buffer)

	// Create a new zip archive.
	w := zip.NewWriter(buf)

	// Register a custom Deflate compressor.
	w.RegisterCompressor(zip.Deflate, func(out io.Writer) (io.WriteCloser, error) {
		return flate.NewWriter(out, flate.BestCompression)
	})

	// Proceed to add files to w.
}
func (*Writer) SetComment
func (w *Writer) SetComment(comment string) error

SetComment 设置中央目录结束记录的注释字段。 它只能在 Writer.Close 之前调用。

func (*Writer) SetOffset
func (w *Writer) SetOffset(n int64)

SetOffset 设置 zip 数据在底层写入器中起始位置的偏移量。 当 zip 数据被追加到已有文件(例如二进制可执行文件)时应当使用它。 它必须在写入任何数据之前调用。