Go archive/zip FileHeader.SetMode 保留压缩条目权限位的处理方法

用 Go 创建 ZIP 时，如果希望条目携带原文件的权限信息，应把 fs.FileMode 写入 zip.FileHeader，再调用 zip.Writer.CreateHeader。FileHeader.SetMode 只负责把模式转换为 ZIP 条目的元数据，不会替你修改磁盘文件，也不保证所有解压工具都恢复 Unix 权限。

官方文档：https://pkg.go.dev/archive/zip#FileHeader.SetMode

FileHeader.SetMode 写入的不是解压动作

zip.FileHeader 描述一个待写入的 ZIP 条目。调用 SetMode 后，Go 会根据传入的 fs.FileMode 填充条目所需的模式信息；随后 CreateHeader 才把这个 header 交给 zip.Writer。因此它解决的是“归档里记录什么”，不是“解压后操作系统一定设置什么”。

如果直接用 zw.Create("app.sh")，就没有机会在创建条目前设置完整 header。需要保留模式时，应先构造 header，再设置名称和模式：

package main

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

func addFile(zw *zip.Writer, name string, mode os.FileMode, r io.Reader) error {
    // 先准备条目元数据，再把 Go 文件模式写入 ZIP header。
    header := &zip.FileHeader{Name: name, Method: zip.Deflate}
    header.SetMode(mode)

    // CreateHeader 成功后才得到当前条目的写入器。
    dst, err := zw.CreateHeader(header)
    if err != nil {
        return fmt.Errorf("创建 ZIP 条目 %q: %w", name, err)
    }
    // Copy 的错误必须向上返回，否则压缩包可能只有半个条目。
    if _, err := io.Copy(dst, r); err != nil {
        return fmt.Errorf("写入 ZIP 条目 %q: %w", name, err)
    }
    return nil
}

func main() {
    src, err := os.Open("app.sh")
    if err != nil {
        panic(err)
    }
    defer src.Close() // 及时释放源文件句柄。

    out, err := os.Create("bundle.zip")
    if err != nil {
        panic(err)
    }
    zw := zip.NewWriter(out)
    if err := addFile(zw, "app.sh", 0o755, src); err != nil {
        panic(err)
    }
    // Close 会写入 ZIP 的中央目录，不能省略或忽略错误。
    if err := zw.Close(); err != nil {
        panic(err)
    }
    if err := out.Close(); err != nil {
        panic(err)
    }
}

创建条目时要保留哪些参数

实际项目里，模式通常来自 os.FileInfo.Mode() 或 fs.FileInfo.Mode()。目录、普通文件和符号链接的模式含义不同，不能为了“看起来完整”统一写成 0o755。下面的判断可以作为归档前的检查清单：

还要注意 header 的名称是归档内路径，不应直接把本地绝对路径塞进去。使用统一的相对路径可以避免把机器目录结构暴露到 ZIP 中，也方便不同系统的解压工具识别条目。

读取端如何判断权限信息是否可用

打开 ZIP 后可以遍历 Reader.File，从每个 zip.File 的 FileHeader.Mode() 读取模式。这个值用于判断归档记录了什么；真正落盘时，应用程序仍应明确决定是否调用 os.Chmod，并在受限目录或不可信归档中拒绝危险权限。

package main

import (
    "archive/zip"
    "fmt"
)

func inspect(path string) error {
    // OpenReader 负责打开归档，使用完必须关闭底层文件。
    zr, err := zip.OpenReader(path)
    if err != nil {
        return err
    }
    defer zr.Close()

    for _, entry := range zr.File {
        mode := entry.Mode()
        // 这里只读取归档元数据，不把它当作已经执行过 chmod 的证明。
        fmt.Printf("%s: type=%s perm=%#o\\n", entry.Name, mode.Type(), mode.Perm())
    }
    return nil
}

如果采用 Reader.Open 按 fs.FS 语义访问条目，路径必须使用正斜杠，且不能包含开头的 / 或 .. 路径段。它解决的是安全、稳定的条目查找；权限恢复仍然是应用层的另一个决策。

跨平台归档的权限边界

Unix 权限位在 Linux、macOS 上更有意义，但 ZIP 格式和解压工具的实现并不统一。生产环境不要把“header 里有 0o755”写成安全承诺：解压工具可能忽略它，也可能根据自身策略过滤特殊位。对于来自外部的 ZIP，建议先把目标目录固定在隔离位置，再按白名单决定是否应用权限；对于内部发布包，则在解压后复查文件类型、路径和最终模式。

这里的检查顺序很简单：归档前确认名称是相对路径；写入后确认 zw.Close() 成功；读取时先看 entry.Mode()，再决定是否创建或修改目标文件。三者缺一不可。

常见问题

SetMode 会直接修改本地文件权限吗？

不会。它只修改待写入的 FileHeader，本地文件权限仍由文件系统和 os.Chmod 等操作控制。

为什么解压后权限没有恢复？

解压工具可能忽略 Unix 模式，或当前平台不支持同样的权限语义。先检查 ZIP 条目的 Mode()，再检查解压器是否提供权限恢复选项。

只调用 CreateHeader 不调用 Close 可以吗？

不可以。zip.Writer.Close 负责写中央目录；忽略它的错误可能得到无法可靠读取的压缩包。