package zip
import "archive/zip"
zip 包提供对 ZIP 归档文件的读写支持。
详情参见 [ZIP 规范]。
本包不支持磁盘跨卷存储。
关于 ZIP64 的说明:
为保持向后兼容,FileHeader 同时包含 32 位和 64 位大小字段。 64 位字段始终存储正确数值,普通归档文件中两类字段值一致。 对于需要使用 ZIP64 格式的文件,32 位字段会设为 0xffffffff,此时必须使用 64 位字段。
Index
- Constants
- Variables
- func RegisterCompressor(method uint16, comp Compressor)
- func RegisterDecompressor(method uint16, dcomp Decompressor)
- type Compressor
- type Decompressor
- type File
- type FileHeader
- type ReadCloser
- type Reader
-
type Writer
- func NewWriter(w io.Writer) *Writer
- func (w *Writer) AddFS(fsys fs.FS) error
- func (w *Writer) Close() error
- func (w *Writer) Copy(f *File) error
- func (w *Writer) Create(name string) (io.Writer, error)
- func (w *Writer) CreateHeader(fh *FileHeader) (io.Writer, error)
- func (w *Writer) CreateRaw(fh *FileHeader) (io.Writer, error)
- func (w *Writer) Flush() error
- func (w *Writer) RegisterCompressor(method uint16, comp Compressor)
- func (w *Writer) SetComment(comment string) error
- func (w *Writer) SetOffset(n int64)
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 归档中提供内容。
Output: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()
}
}
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 数据被追加到已有文件(例如二进制可执行文件)时应当使用它。 它必须在写入任何数据之前调用。