当前位置：首页 > news >正文

Python Bug 修复案例分析：编码问题导致程序出现bug 两种修复方法

news 2025/6/25 9:43:40

前期开发了一个简单的文件处理程序，用于批量重命名和压缩图片。但在处理包含中文名称的文件时，程序总是崩溃。让我们一步步分析并修复这个问题。

一、问题描述

用户使用反馈：

"当选择的文件夹中包含中文名称的图片时，程序直接崩溃，错误信息显示 'UnicodeEncodeError: 'ascii' codec can't encode characters in position...'"

二、复现问题

以下是引发崩溃的原始代码

import os
import zipfiledef compress_images(folder_path, output_zip):with zipfile.ZipFile(output_zip, 'w') as zipf:for root, dirs, files in os.walk(folder_path):for file in files:if file.endswith(('.jpg', '.png')):file_path = os.path.join(root, file)# 问题代码：直接使用原始文件名zipf.write(file_path, file)print(f"压缩完成: {output_zip}")# 使用示例
compress_images("D:/图片/旅行", "旅行照片.zip")

三、调试与分析

错误信息解析：
UnicodeEncodeError: 'ascii' codec can't encode characters in position...
→ Python 默认使用 ASCII 编码处理字符串，而中文等非 ASCII 字符无法被正确编码。
关键排查点：
- zipf.write(file_path, file) 这一行将文件添加到 ZIP 时，file（中文文件名）无法被 ASCII 编码。
- Windows 系统默认文件名编码为 GBK，而 Python 脚本默认使用 UTF-8。
简化测试用例

# 验证编码问题
filename = "中文图片.jpg"
print(filename.encode('ascii'))  # 直接触发 UnicodeEncodeError

四、bug修复方案

方案 1：指定 ZIP 文件编码为 UTF-8

import os
import zipfiledef compress_images(folder_path, output_zip):with zipfile.ZipFile(output_zip, 'w', compression=zipfile.ZIP_DEFLATED) as zipf:for root, dirs, files in os.walk(folder_path):for file in files:if file.endswith(('.jpg', '.png')):file_path = os.path.join(root, file)# 获取相对路径，避免包含完整路径arcname = os.path.relpath(file_path, folder_path)# 指定编码为UTF-8zipf.write(file_path, arcname.encode('utf-8').decode('utf-8'))print(f"压缩完成: {output_zip}")

方案 2：使用系统默认编码

import os
import zipfile
import sysdef compress_images(folder_path, output_zip):# 获取系统默认文件系统编码fs_encoding = sys.getfilesystemencoding()with zipfile.ZipFile(output_zip, 'w') as zipf:for root, dirs, files in os.walk(folder_path):for file in files:if file.endswith(('.jpg', '.png')):file_path = os.path.join(root, file)arcname = os.path.relpath(file_path, folder_path)# 使用系统编码处理文件名arcname_encoded = arcname.encode(fs_encoding, errors='replace')arcname_decoded = arcname_encoded.decode('utf-8', errors='replace')zipf.write(file_path, arcname_decoded)

五、bug验证修复

测试中文文件名：
创建包含中文名称的图片文件（如 风景.jpg），运行修复后的代码，确认不再崩溃。
解压验证：
解压生成的 ZIP 文件，检查文件名是否保持正确（中文未乱码）。
边缘情况测试：
- 包含特殊字符的文件名（如 !@#$%^&*.jpg）。
- 不同系统（Windows/Linux/macOS）下的兼容性。