Go archive/zip 读取中文文件名时怎么处理 UTF-8 标记

Go 的 archive/zip 读取中文文件名时，先不要直接把 f.Name 当成“肯定是 UTF-8”，也不要看到 NonUTF8 就盲目按 GBK 转换。正确做法是先看 ZIP 条目的 UTF-8 标志，再结合压缩包来源决定是否做显式转码。标准库已经把文件名读成 Go 字符串；真正需要兼容的是“这个字节串应该按什么编码解释”。

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

由 Go 生成的合法中文名称通常会设置 ZIP 的 UTF-8 标志。读取第三方压缩包时，如果 File.NonUTF8 为 true，只能说明名称不是明确的 UTF-8 或存在编码歧义；只有在业务已确认来源使用 GBK、GB18030 等编码时，才应按约定转换。

先把乱码现象拆成三个可观察信号

读取时通常遍历 Reader.File。每个 File 都带有 FileHeader 的名称、标志位和 NonUTF8 信息。第 11 个通用目的位，也就是十六进制 0x800，是 ZIP 规范中声明文件名和注释采用 UTF-8 的位置。

package main

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

func main() {
    zr, err := zip.OpenReader("incoming.zip")
    if err != nil {
        log.Fatal(err) // 打不开归档时立即停止，不继续使用空 Reader
    }
    defer zr.Close() // 释放底层文件描述符

    for _, f := range zr.File {
        utf8Flag := f.Flags&0x800 != 0
        fmt.Printf("name=%q utf8Flag=%v nonUTF8=%v\n", f.Name, utf8Flag, f.NonUTF8)
    }
}

这里的三个信号用途不同：f.Name 是标准库已经解析出的名称；utf8Flag 是归档写入者的显式声明；f.NonUTF8 是 Go 结合名称字节和标志位推断出的结果。中文字符本身不能证明编码，因为一段 GBK 字节也可能恰好构成“看起来像”另一种解释。

为什么缺少 UTF-8 标记不能直接判定为 GBK

Go 源码在读取名称时会先判断字节是否为有效 UTF-8。对明显不是 UTF-8 的内容，NonUTF8 会被置为 true；对既可能是 UTF-8、又可能是其他本地编码的内容，标准库会信任 ZIP 里的标志位。这是因为仅凭一串字节无法可靠地区分 GBK、Shift-JIS 或某些历史本地编码。

因此，“缺少 UTF-8 标志”与“使用 GBK”不是同一个结论。先记录 CreatorVersion、来源系统或打包工具，再决定兼容方案，比在代码里根据文件名猜编码更稳妥。

确定来源编码后再做显式转码

如果上游合同明确规定“文件名按 GB18030 写入”，可以把标准库保留的原始字节重新交给对应解码器。下面示例只演示边界：默认路径不转码，只有调用方明确传入编码时才转换。

package main

import (
    "fmt"
    "golang.org/x/text/encoding/simplifiedchinese"
    "golang.org/x/text/transform"
    "io"
    "strings"
)

func decodeName(name string, encodingName string) (string, error) {
    if encodingName == "" {
        return name, nil // 没有来源约定时保留 archive/zip 的原始判断
    }
    if encodingName != "gb18030" {
        return "", fmt.Errorf("unsupported filename encoding: %s", encodingName)
    }
    reader := transform.NewReader(strings.NewReader(name), simplifiedchinese.GB18030.NewDecoder())
    decoded, err := io.ReadAll(reader)
    if err != nil {
        return "", fmt.Errorf("decode zip filename: %w", err) // 转码失败必须暴露
    }
    return string(decoded), nil
}

这段代码的前提是你确实知道字节来自 GB18030。若压缩工具把中文直接按 UTF-8 写入却忘记设置标志位，强行套 GB18030 反而会产生新的乱码。生产代码还应把“来源编码”作为配置或元数据记录，而不是写死成自动猜测。

名称解码完成后还要单独检查路径安全

文件名显示正常，不代表可以安全落盘。ZIP 条目仍可能包含绝对路径、../ 或反斜杠。Go 当前文档说明，设置 GODEBUG=zipinsecurepath=0 时，NewReader 会针对非本地名称返回 ErrInsecurePath；名称编码处理与解压路径校验是两条独立边界，不能互相替代。

落盘前建议依次做三件事：记录原始 f.Name 与解码后的展示名；拒绝绝对路径和父目录跳转；对目录条目（名称以斜杠结尾）与普通文件分别处理。需要读取内容时调用 f.Open()，并及时关闭返回的读取器。

常见问题

为什么在 Windows 打包的 ZIP 中中文名有时正常、有时乱码？

不同压缩工具可能选择 UTF-8 标志、系统本地编码或额外字段，文件名内容相同但元数据不同。先比较 Flags 和 NonUTF8，再按打包工具确认编码。

把 string(f.Name) 再转一次 UTF-8 可以吗？

通常不可以。Go 的字符串只是字节序列，重复转码不会自动知道原编码；明确的 GBK/GB18030 来源才值得使用对应解码器。

读取名称和安全解压是不是一回事？

不是。名称是否正确解决可读性，路径是否本地安全解决文件写入边界，两者必须分别判断。

排查中文文件名时，先保留标准库的判断和来源信息，再做有依据的单一转码，最后单独完成路径安全检查，通常比“见乱码就换编码”更容易定位问题。