Ruby处理Zip文件时UTF-8无效字节序列问题求解

阿华AIGC实验室

2026-5-11

解决Ruby处理Zip文件时的UTF-8编码异常问题

我之前处理过不少跨平台Zip文件的编码问题，尤其是macOS下处理Windows生成的Zip，很容易遇到这类编码错误。结合你的代码和问题，我整理了几个关键修复点：

1. 核心问题：文件名编码识别错误

你遇到的「invalid byte sequence in UTF-8」是因为Zip文件中的文件名可能不是用UTF-8编码的（比如Windows系统生成的Zip常用CP437或GBK编码）。直接用encode!("UTF-8", "UTF-8", ...)相当于强行把非UTF-8字节当成UTF-8处理，替换后自然会显示乱码。

正确的做法是先识别文件名的原始编码，再转换为UTF-8：

对于大多数Windows生成的Zip，文件名编码是CP437（Ruby的zip库默认也会用这个编码解析文件名）
可以先尝试验证编码有效性，再进行转换

2. 修复代码中的逻辑错误

你的代码里有几处明显的逻辑问题，比如dir + ".txt" || ".jpg" || ".csv"完全不符合预期——逻辑或||在这里只会返回第一个非空值，不会根据后缀切换。另外，多余的force_encoding和冗余的重命名步骤也可以优化。

完整修复后的代码

Zip::File.open_buffer(obj) do |zip|
  zip.each do |entry|
    # 第一步：正确处理文件名编码
    entry_name = entry.name
    # 先尝试用CP437解码（Windows Zip常见编码），再转UTF-8，替换无效字符
    if entry_name.valid_encoding?
      normalized_name = entry_name.encode("UTF-8")
    else
      normalized_name = entry_name.force_encoding("CP437").encode(
        "UTF-8",
        invalid: :replace,
        undef: :replace,
        replace: "?" # 用问号替换无法识别的字符，也可以换成其他符号
      )
    end

    ext = File.extname(normalized_name)
    file_name = File.basename(normalized_name)

    # 过滤条件保持不变
    next if ext.blank? || file_name.count(".") > 1

    # 生成目标目录并确保编码正确
    dir = File.join(dir_name, File.dirname(normalized_name)).encode(
      "UTF-8",
      invalid: :replace,
      undef: :replace
    )
    FileUtils.mkpath(dir)

    # 直接提取到目标路径，避免冗余的重命名步骤
    target_path = File.join(dir, file_name)
    zip.extract(entry, target_path) { true } # 强制覆盖已存在的文件

    # 添加到输入目录列表
    @input_dir << target_path.encode("UTF-8")
  end
end

# 重新打包部分保持逻辑不变，确保路径编码正确
Zip::OutputStream.open(zip_file.path) do |zip_data|
  @input_dir.each do |file|
    # 确保entry名称是UTF-8编码
    zip_data.put_next_entry(File.basename(file).encode("UTF-8"))
    zip_data.write(File.read(file))
  end
end