Go ZIP 为什么文件名出现乱码

我第一次遇到这个问题，是把一个在 Windows 工具里能正常显示中文文件名的 ZIP 交给 Go 服务处理，结果日志里的条目名像是被“重新加密”了一遍。后来我发现，压缩内容通常没坏，真正不稳定的是 ZIP 条目名称的字节和解压工具采用的解释方式。

简单说：Go 用 archive/zip 创建中文文件名时，默认会按有效 UTF-8 处理并设置 ZIP 的 UTF-8 标志；旧压缩包如果把本地编码字节写进文件名字段，Go 只能把它当作非 UTF-8 信号交给你判断，不能凭空知道它究竟是 GBK、Shift-JIS 还是别的编码。

官方地址：https://pkg.go.dev/archive/zip

先把乱码定位到 ZIP 文件名编码

ZIP 文件名字段本质上是字节。规范约定可以使用 CP437；当通用标志位的第 11 位打开时，名称按 UTF-8 解释。但历史工具并不总是遵守同一套约定：有的工具写入本地编码，有的工具不设置 UTF-8 标志却仍写入 UTF-8，还有的解压器会把未标记的字节直接按操作系统区域设置解释。

Go 的 zip.FileHeader 提供了 Name 和 NonUTF8。后者只能说明名称或注释不应被当成 UTF-8，不能直接推出“它一定是 GBK”。同一份非 UTF-8 ZIP，在中文 Windows、Linux 和 macOS 上显示不同，通常就是解释端的默认编码不同。

创建 ZIP 时让 Go 写出可移植名称

如果 ZIP 由你的 Go 服务生成，最稳妥的策略是让文件名保持有效 UTF-8，并使用默认的 Writer.Create 或 CreateHeader。不要为了“兼容中文 Windows”随手把 NonUTF8 设为 true：它只会清除 UTF-8 标志，不会替你把 UTF-8 字符串转换成某一种本地编码。

package main

import (
    "archive/zip"
    "bytes"
)

func addUTF8Entry(w *zip.Writer, name string, data []byte) error {
    // name 保持有效 UTF-8；Go 会根据名称内容处理 ZIP 的 UTF-8 标志。
    header := &zip.FileHeader{Name: name, Method: zip.Deflate}
    entry, err := w.CreateHeader(header)
    if err != nil {
        return err
    }
    // 先创建条目，再一次性写入内容，避免遗漏写入错误。
    _, err = bytes.NewReader(data).WriteTo(entry)
    return err
}

真正跨平台交付时，还要确认接收方使用的解压工具支持 UTF-8 文件名。若业务必须产出面向某个旧系统的本地编码 ZIP，就应在接口文档里写清目标编码、测试工具和失败回退，而不是只改一个布尔字段。

读取旧 ZIP 时按来源决定解码

读取端最容易误判的是：看到 f.NonUTF8 就无条件按 GBK 解码。这个字段只提供“不要把它当作标准 UTF-8”的线索；只有当文件来源明确约定为 GBK 或 GB18030 时，才可以使用对应解码器。来源不明时，宁可保留原始显示、记录包来源和标志位，也不要静默把日文或其他编码改坏。

package main

import (
    "archive/zip"
    "golang.org/x/text/encoding/simplifiedchinese"
)

func displayName(f *zip.File, sourceIsGBK bool) string {
    // NonUTF8 只表示存在非 UTF-8 线索，不能单独证明编码是 GBK。
    if !f.NonUTF8 || !sourceIsGBK {
        return f.Name
    }
    // 只有来源协议确认是 GBK 时，才把原始字节按 GBK 解码。
    decoded, err := simplifiedchinese.GBK.NewDecoder().String(f.Name)
    if err != nil {
        // 解码失败时保留原名，避免把错误扩大成不可追踪的空名称。
        return f.Name
    }
    return decoded
}

这里的关键不是“找到一个万能转换函数”，而是把编码判断放在业务边界：谁生成 ZIP、生成工具采用什么约定、这个批次是否始终来自同一系统。若需要支持多个来源，可把来源到编码的映射配置化，并为未知来源保留原名和告警字段。

我现在会用这份边界清单

我的经验是，先修生成端比在读取端堆更多猜测可靠。只有必须接收旧包时，才把“来源确认—编码映射—失败保留原名”做成明确流程。相关标准入口可查看 https://support.pkware.com/pkzip/appnote，Go 标准库的字段语义则以 https://pkg.go.dev/archive/zip 为准。

常见问题

NonUTF8 为 true 就一定是 GBK 吗？

不是。它只表示名称或注释不应直接按 UTF-8 处理；具体编码需要结合生成工具、地区和接口协议判断。

能不能在 Go 中把 NonUTF8 设为 true 来修乱码？

不能把它当转换开关。它改变的是 ZIP UTF-8 标志，真正的 GBK 或其他本地编码转换必须在你明确知道目标编码时单独完成。

为什么压缩包能解开，但文件名仍然乱码？

压缩数据和条目名称是两部分元数据。解压器能正确解压内容，只说明压缩算法和数据块可读，不代表文件名的字节解释一致。