zip 文件名编码异常时的读取策略

Go 读取 ZIP 时中文文件名异常，通常不是“把字符串再转一次 UTF-8”就能解决。先看 ZIP 是否声明了 UTF-8，再看 FileHeader.NonUTF8，最后确认压缩工具实际写入的是 CP437 还是 GBK 等本地编码。archive/zip 不会根据运行环境自动猜测 GBK；遇到历史本地编码包，应在能拿到原始文件名字节的位置显式解码，并把解码与路径安全分成两层。

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

先判断 ZIP 名称到底按什么编码

ZIP 文件名的关键线索在目录项的编码标志，而不是操作系统当前的语言环境。Go 文档说明：有效 UTF-8 名称会由 Writer 自动设置 UTF-8 标志；NonUTF8 表示名称和注释不是 UTF-8，规范允许的另一编码是 CP437，但历史工具经常写入本地字符集。

通过 NonUTF8 和样本名称定位问题

第一步只做观察，不要立即改名。把 Name、NonUTF8、是否目录以及原始压缩工具记录下来；同一个 ZIP 同时放一个 ASCII 文件和一个中文文件，能帮助判断是整体标志问题还是单个目录项异常。

package main

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

func main() {
    r, err := zip.OpenReader("archive.zip")
    if err != nil {
        log.Fatal(err) // 打开失败先保留原始错误，不把它误判成乱码
    }
    defer r.Close() // Reader 持有文件资源，遍历结束后必须关闭

    for _, f := range r.File {
        fmt.Printf("name=%q nonUTF8=%t dir=%t\n", f.Name, f.NonUTF8, f.FileInfo().IsDir()) // 记录线索供后续判断
    }
}

这里的 NonUTF8=true 只能说明 ZIP 没有把名称当作 UTF-8；它不能证明名称就是 GBK。尤其不要写成 string([]byte(f.Name)) 再转一次，这只会破坏已经正确解码的 Unicode 字符。

历史本地编码要建立显式解码适配层

如果确认来源是 GBK 或 GB18030，标准库的 archive/zip 没有公开一个“传入文件名解码器”的入口。可靠方案有两种：让上游压缩工具重新生成带 UTF-8 标志的 ZIP；或者选用能暴露目录项原始名字节的解析层，在那里完成解码，再把得到的 Unicode 名称交给后续业务。

package names

import (
    "fmt"

    "golang.org/x/text/encoding/simplifiedchinese"
)

func decodeGB18030(raw []byte) (string, error) {
    text, err := simplifiedchinese.GB18030.NewDecoder().String(string(raw)) // 只在确认来源编码后转换
    if err != nil {
        return "", fmt.Errorf("decode zip filename: %w", err) // 保留失败原因，避免静默替换字符
    }
    return text, nil
}

这个函数的输入必须是目录项里的原始字节，不能把 f.Name 当成原始字节。解码器的选择要和压缩包来源绑定，并用包含中文、全角符号和目录分隔层级的样本回归。

解码之后还要做路径安全处理

文件名显示正常，不代表可以安全落盘。Go 文档提醒 ZIP 名称可能包含绝对路径、.. 或反斜杠；较新的读取接口还会在特定 GODEBUG 设置下报告 ErrInsecurePath。解码完成后，统一使用斜杠、拒绝非本地路径，并对规范化后的名称做重名检测。

func safeName(name string) (string, error) {
    name = strings.ReplaceAll(name, "\\\\", "/") // 先统一分隔符，避免跨平台语义不一致
    clean := path.Clean(name)
    if clean == "." || path.IsAbs(clean) || clean == ".." || strings.HasPrefix(clean, "../") {
        return "", fmt.Errorf("拒绝不安全 ZIP 名称: %q", name) // 不把不可信路径带入目标目录
    }
    return clean, nil
}

示例需要补充 fmt、path 和 strings 导入。实际提取时，把安全名称映射到一个已确认的目标根目录，并拒绝规范化后的重名；不要用用户提供的名称直接做字符串拼接。

常见问题

NonUTF8 为 true 就一定是 GBK 吗？

不是。它只表示不是 UTF-8，规范上还可能是 CP437，历史工具也可能使用其他本地编码。

已经拿到 FileHeader.Name，还能恢复原始 GBK 字节吗？

通常不能可靠恢复。名称可能已经按另一套规则解码，应该在更早的目录解析层保留原始字节。

文件名修好后为什么仍然不能解压？

编码和路径是两个问题；绝对路径、../、反斜杠以及规范化后的重名都可能让安全提取失败。