我给自己写了一个本地文件编码转换器：批量转码、换行统一、原文件可回退

目录

1. 缘起：文件能打开，不代表编码没有问题
2. 需求拆解：转码工具首先要避免误判
3. 技术选型：标准库足够覆盖常见编码
4. 核心实现一：BOM 检测与可解释的预览
5. 核心实现二：批量转换与原子写入
6. UI 定制：让用户在执行前看到风险
7. 三个编码转换最容易踩的坑
8. 结尾：编码转换的目标是让内容保持原样

1. 缘起：文件能打开，不代表编码没有问题

我处理旧项目时经常遇到一种很隐蔽的故障：文件在当前编辑器里显示正常，换到构建脚本、Linux 服务器或另一台电脑上就出现乱码。更麻烦的是，乱码不一定在打开文件时立刻出现，可能直到程序读取某个中文配置项才暴露。

目录里的文本文件通常比想象中复杂：

• 新文件是 UTF-8，旧文件可能是 GBK 或本地代码页；
• 同一个目录里混着带 BOM 和不带 BOM 的 UTF-8；
• Windows 换行和 Unix 换行交错出现；
• 某些导出工具把制表符、不可见控制字符一起写进内容；
• 文件扩展名无法说明实际编码。

遇到问题时，我不想每个文件都手动打开、选择编码、另存为。于是写了一个本地转换工具，先展示检测结果和抽样内容，确认规则后再批量输出。

2. 需求拆解：转码工具首先要避免误判

字符编码不存在“看到几个汉字就能绝对猜中”的万能识别方法。因此工具的重点不是假装聪明，而是把证据、候选和不确定性展示出来。

第一版只处理纯文本和常见配置文件，不碰二进制文件。即使某个二进制文件恰好能被某种编码解码，也不能因此把它当成文本写回。

心得：编码工具最危险的功能不是转换失败，而是转换成功却悄悄改变了内容。

3. 技术选型：标准库足够覆盖常见编码

Python 标准库已经支持主要目标编码：

我没有把“自动猜编码”作为唯一入口。UTF-8、GBK 和某些单字节编码之间存在大量可解码的字节序列，自动算法可能给出一个看似合理却错误的结果。程序可以提供候选建议，但必须允许用户确认源编码。

读取大文件时使用流式方式统计字节数和解码错误，但预览只取开头一小段。转换过程中仍然按块读取，不把整个几十兆的日志一次性放进内存。

4. 核心实现一：BOM 检测与可解释的预览

BOM 是一个很有用的证据，但它只覆盖部分文件。程序先读取文件头，再决定默认编码：

BOMS = [
    (b"\xef\xbb\xbf", "utf-8-sig"),
    (b"\xff\xfe\x00\x00", "utf-32"),
    (b"\x00\x00\xfe\xff", "utf-32-be"),
    (b"\xff\xfe", "utf-16"),
    (b"\xfe\xff", "utf-16-be"),
]

def detect_bom(header):
    for marker, encoding in BOMS:
        if header.startswith(marker):
            return encoding, len(marker)
    return None, 0

没有 BOM 时，程序不声称“已经识别成功”，而是按用户选择的候选编码尝试解码，并记录错误数量：

def preview(path, encoding, limit=8192):
    raw = path.read_bytes()[:limit]
    text = raw.decode(encoding, errors="replace")
    replacements = text.count("\ufffd")
    return text, replacements

预览区域同时显示原始字节数、候选编码、替换字符数量和检测到的 BOM。只要出现替换字符，转换按钮就变成“确认后继续”，避免用户把乱码结果当成正常文本写出。

抽样内容还会显示不可见字符：Tab 用小箭头表示，行尾用标记表示，控制字符则显示十六进制。很多“编码问题”其实是文件里混入了不可见分隔符，单看正常文字很难发现。

5. 核心实现二：批量转换与原子写入

批量转换前先扫描并生成计划。每项包含源路径、目标路径、源编码、目标编码和换行策略。计划中存在任何无法解码的文件，都先暂停执行而不是边转边报错。

文本写入使用临时文件和原子替换：

import os
import tempfile

def write_safely(target, text, encoding, newline):
    target.parent.mkdir(parents=True, exist_ok=True)
    fd, temp_name = tempfile.mkstemp(
        prefix=f".{target.name}.",
        suffix=".tmp",
        dir=target.parent,
    )

    try:
        with os.fdopen(fd, "w", encoding=encoding, newline="") as file:
            file.write(normalize_newlines(text, newline))
            file.flush()
            os.fsync(file.fileno())
        os.replace(temp_name, target)
    finally:
        if os.path.exists(temp_name):
            os.unlink(temp_name)

换行统一不使用简单的字符串替换，因为 \r\n 如果先替换 \n，可能产生重复回车。先把所有换行拆成逻辑行，再按目标格式连接：

def normalize_newlines(text, newline):
    lines = text.splitlines()
    return newline.join(lines) + (newline if text.endswith(("\n", "\r")) else "")

目标目录默认是源目录旁边的 converted。如果目标文件已经存在，程序列为冲突，不覆盖。转换完成后可以重新读取目标文件，用目标编码解码并计算字符数，作为基本的回读校验。

6. UI 定制：让用户在执行前看到风险

界面顶部选择输入目录、输出目录和文件扩展名过滤器。中间表格展示每个文件的状态：

文件名 | 检测编码 | 目标编码 | 换行 | 预览状态 | 输出状态

点击某一行，右侧显示原编码和目标编码下的预览对照。程序不把两个文本当成差异比较，而是关注字符是否能被正确解码、换行是否按规则转换。

目标编码选择旁边显示兼容说明：UTF-8 适合跨平台，UTF-8 with BOM 适合部分旧版 Windows 工具，GB18030 适合需要兼容中文本地代码页的系统。说明不是强制规则，但能减少“随便选一个编码”的情况。

批量开始前，界面统计待处理文件数、预计输出体积和潜在风险文件数。用户可以取消单个文件，也可以先导出计划报告再执行。

执行完成后，程序列出成功、解码失败、目标冲突和权限失败。任何失败都不会让整批结果被标记为“全部成功”。

7. 三个编码转换最容易踩的坑

坑一：能解码不代表编码正确。 GBK 和某些单字节编码可能把同一段字节解码成看似正常的文字。工具无法仅凭“没有异常”证明选择正确，因此必须提供预览和用户确认；对重要文件还应结合来源系统和历史格式判断。

坑二：BOM 不能简单当成内容字符。 使用 utf-8 读取带 BOM 的文件，可能把 BOM 变成开头的不可见字符；使用 utf-8-sig 则会在读取时处理它。输入和输出编码要分别管理，不能看到 BOM 就在正文里手动删除一个字符。

坑三：换行转换可能破坏文件末尾约定。 有的工具要求最后一行必须有换行，有的生成文件则刻意不加。程序把“是否保留末尾换行”作为单独状态，不把所有文本无条件追加换行符。

另外，文件名本身也可能不是 UTF-8 文本内容，不能因为正文转换成功就重新编码路径。批量工具只处理文件内容，路径保持系统原样。

8. 结尾：编码转换的目标是让内容保持原样

这个工具最终没有变成一个“自动猜一切”的黑盒。它更像一个有证据的转换流程：先看 BOM 和预览，再确定源编码；先生成计划，再安全输出；最后回读目标文件并记录结果。

一次可靠的转码应该包含这些步骤：

1. 确认文件确实是文本；
2. 识别或选择源编码；
3. 预览解码结果并检查替换字符；
4. 明确目标编码和换行策略；
5. 输出到新目录并回读校验。

如果你也要处理一批老文件，可以先从单文件预览开始，不要直接对整个目录执行覆盖式转换。编码问题最怕批量放大，先让一个样本完全正确，再推广规则。

转码不是把字节换一种写法那么简单，它是在不同工具之间搬运文字。工具真正要保护的，是内容本身不因为格式变化而悄悄走样。