⚡

CSV编码修复医生Skill csv-encoding-doctor

一个纯 Python 标准库(零第三方依赖)的 CSV/TSV/TXT 编码与格式诊断修复技能:先体检再修复、最后做一致性校验。体检阶段不靠猜,而是输出候选编码并打分(用中文高频字命中率区分 GB18030 与 Big5,压低西文高位字节误判),同时用状态机识别换行(跳过引号内换行),判定真实分隔符(逗号/分号/TAB/竖线);修复阶段可完成 GBK↔UTF-8↔UTF-16 互转、增删 UTF-8 BOM、CRLF/LF 统一、分隔符统一、去首尾空白、全角转半角、删除空行、公式注入转义、可选出引号,并支持 dry-run 与原地覆盖(自动备份);校验阶段用归一化比较确认“改完还是原来的数据”。脚本以退出码作为契约,可直接接入数据流水线。适用于 Excel 打开中文乱码、首列出现 \ufeff、所有列挤在第一列、数字变文本无法求和、列数不齐、导入系统报格式错误、pandas 报 UnicodeDecodeError 等场景。关键词:CSV乱码修复、编码检测、GBK转UTF-8、UTF-8 BOM、gb18030、分隔符识别、换行符统一CRLF/LF、全角转半角、列数不齐ragged、公式注入防护、数据清洗、数据格式归一化、Python csv模块、数据导入报错排查、Excel中文乱码、UnicodeDecodeError、零依赖脚本、数据流水线校验。

数据工程 0 次安装 0 次浏览 更新于 11/22/2026
名称 csv-编码修复医生
描述 诊断并修复 CSV/TSV/TXT 的编码与格式问题——GBK↔UTF-8 乱码、UTF-8 BOM 导致首列名带 \ufeff、CRLF/LF 混用、分号/逗号/TAB 分隔符不匹配、全角数字变文本、列数不齐、公式注入。纯 Python 标准库,无需 pandas。 when_to_use: 用户提到 CSV 乱码、Excel 打开中文乱码、编码转换、GBK 转 UTF-8、带 BOM、分隔符不对、所有列挤在一列、全角数字、列数对不上、导入系统报格式错误、pandas 读取报 UnicodeDecodeError
版本 1.0.0
开源协议 MIT

CSV 编码体检与修复

这个技能解决什么

拿到一个 CSV,先回答三个问题,再动手改:

  1. 它到底是什么编码? 不能靠猜,也不能只靠 chardet 的单一结论 —— 本技能给出候选编码 + 打分,把误判概率显式化。
  2. 它的换行和分隔符是什么? 中文环境下 80% 的“所有列挤在第一列”,是分隔符判定错了,不是数据坏了。
  3. 改完还是原来的数据吗? 必须有前后一致性校验,否则修完不敢用。

三步工作流

# 第 1 步:体检(不改文件)
python scripts/diag.py 台账.csv
python scripts/diag.py ./exports --json        # 批量

# 第 2 步:修复(默认输出 台账.fixed.csv,不动原文件)
python scripts/fix.py 台账.csv \
  --to-enc utf-8-sig --to-delim , --eol crlf \
  --strip --halfwidth

# 第 3 步:校验(归一化比较,全角/空白差异不计)
python scripts/verify.py 台账.csv 台账.fixed.csv

# 用了 --drop-empty / --fix-formula 时,把这两项声明成有意改动,否则会被报成差异
python scripts/verify.py 台账.csv 台账.fixed.csv --ignore formula,empty

退出码是契约,可以直接接进流水线: diag.py 0=干净 1=有问题 2=读不到;fix.py 0=成功 1=有字符装不下目标编码;verify.py 0=一致 1=有差异。

目标格式怎么定(按接收方选,不要按喜好选)

接收方 编码 BOM 换行 分隔符
Excel 双击打开(中文 Windows) utf-8-sig 要 CRLF ,
老系统 / 政务 / 银行导入 gbk 或 gb18030 不要 CRLF , 或 |
Python / pandas / 数据库 COPY utf-8 不要 LF ,
大数据平台(Hive/Spark) utf-8 不要 LF , 或 \t
欧洲区域设置导出的 Excel utf-8-sig 要 CRLF ;

判定口诀:带 BOM 为了 Excel 认中文,去 BOM 为了程序和数据库不把 \ufeff 当字段名。

参数速查

fix.py

参数 取值 说明
--from-enc auto(默认)/ gbk / utf-8 / utf-16 源编码,auto 走探测
--to-enc utf-8-sig(默认)/ utf-8 / gbk / gb18030 / utf-16 目标编码
--to-delim , ; tab pipe 或字面字符 目标分隔符
--eol keep(默认)/ lf / crlf 目标换行
--quote minimal(默认)/ all all 给每个字段加引号,老系统更稳
--strip 开关 去单元格首尾空白(含全角空格)
--halfwidth 开关 全角数字/字母/标点转半角
--drop-empty 开关 删全空行
--fix-formula 开关 公式开头的单元格加前导 '
--inplace 开关 原地覆盖,自动生成 .bak(不覆盖已有备份)
--dry-run 开关 只报告,不写盘

症状 → 命令

症状 命令
Excel 打开全是乱码 fix.py 文件.csv --to-enc utf-8-sig
首列表头变成 \ufeff姓名 fix.py 文件.csv --to-enc utf-8
所有内容挤在第一列 先 diag.py 看分隔符,再 fix.py --to-delim ,
数字列变成文本、无法求和 fix.py 文件.csv --halfwidth
导入报“列数不匹配” diag.py --json 看 ragged_records,定位到具体第几条
pandas 报 UnicodeDecodeError diag.py 拿编码,读取时显式 encoding=
转到 GBK 后出现问号 fix.py 退出码 1 会报出装不下的字符,改投 --to-enc gb18030

实现要点(改代码前先读)

  • 换行必须在解码后的文本上数。 UTF-16 的字节层是 b"\r\x00 \x00",字节级 count 全错。
  • 引号内的换行不是记录分隔符。 csvkit.detect_newlines 用状态机跳过引号区间,否则带备注换行的文件会被误判“混合换行”。
  • 编码打分用中文高频字命中率。 Big5 被误当 GB18030 解出来的字全是生僻字,命中率趋近 0,这一条能把两种东亚编码分开;纯西文解出高位字节的一律压到 0.3 分以下。
  • 写文件用 csv.writer + lineterminator,不要手动拼字符串。 否则单元格里的逗号、引号、换行全部炸掉。
  • --to-enc gbk 可能装不下 emoji 和生僻字,此时脚本逐字探测,替换成 ? 并返回退出码 1,绝不静默丢数据。

自检

python scripts/selftest.py

造 GBK+分号+全角+空白+单元格内换行的脏文件,跑完整链路,17 项断言。改动代码后先跑这个。

拿 examples 里的脏数据先跑一遍

python scripts/diag.py examples/sample_gbk.csv
python scripts/fix.py examples/sample_gbk.csv --to-enc utf-8-sig --to-delim , --eol crlf \
  --strip --halfwidth --drop-empty --fix-formula
python scripts/verify.py examples/sample_gbk.csv examples/sample_gbk.fixed.csv --ignore formula,empty

预期:diag 报 4 条问题(空白 1 / 公式 2 / 空行 1 / 全角 17),fix 报 6 行→5 行,verify 差异 0 处,再对 .fixed.csv 跑 diag 结论为「干净」。

不适用

  • 嵌套 JSON / XML 字段的 CSV(本技能不做字段内解析)
  • 一个文件里混了两种编码(必须先用 split 按字节边界分段,再分别处理)
  • XLSX(先另存为 CSV,或用 openpyxl 单独处理)

文件清单

SKILL.md
requirements.txt            说明零第三方依赖
scripts/csvkit.py           共用库:BOM/编码打分/换行状态机/分隔符判定/全角转半角
scripts/diag.py             体检:notes 与 issues 分开,支持 --json 与批量
scripts/fix.py              归一化:编码/分隔符/换行/空白/全角/公式/空行
scripts/verify.py           前后一致性校验(归一化比较)
scripts/selftest.py         端到端自检 17 项
examples/sample_gbk.csv     脏数据样例(GBK + 分号 + CRLF + 全角 + 空白 + 公式 + 空行 + 单元格内换行)
examples/sample_gbk.fixed.csv  上例跑完三件套的产物(UTF-8 BOM + 逗号 + 半角 + 公式已转义)
references/pitfalls.md      12 个真实踩坑与数值