故障排查
CSV 导入失败 / 乱码
UTF-8 + 一致日期格式 + 合理行数 + 干净分隔符 — 四件事保证导入成功。
症状
想把外部 CSV 拉进 Kition 数据表，结果遇到三种典型失败：（1）导入按钮点了没反应、（2）导入成功但中文显示成 阿填浴、（3）日期 / 数字字段全识别成"文本"。
所有问题都可归到三类：编码错（90% 是 UTF-8 vs GBK / Windows-1252）、结构错（缺表头、分隔符不一致、引号不平衡）、体量过大（一次性 > 10K 行）。
检查清单
- 文件编码必须是 UTF-8（macOS Numbers / 国内 Excel 默认是 GBK 或 Windows-1252）
- 首行是字段名，且字段名里没有
,也没有换行 - 日期统一为 ISO 8601（
YYYY-MM-DD或YYYY-MM-DD HH:MM:SS） - 单元格里如果有
,必须用"..."包，且内部"要写成"" - 行数控制在 10K 以下；更大文件分批导
- 不要混用
,和;作分隔符
逐步诊断
在 import 之前花 30 秒先看一下文件，能避免 90% 的失败：
# Detect encoding (macOS / Linux ship with 'file')
file -I data.csv
# expect: text/csv; charset=utf-8
# If charset shows iso-8859-1, gbk, or unknown — convert it:
iconv -f GBK -t UTF-8 data.csv > data.utf8.csv
# or for Windows-1252:
iconv -f WINDOWS-1252 -t UTF-8 data.csv > data.utf8.csv
# Quick row count
wc -l data.csv
# Peek at line lengths to spot delimiter issues
awk -F',' '{print NF}' data.csv | sort | uniq -c
# every line should have the same field count修复
- 编码错：
iconv -f GBK -t UTF-8 in.csv > out.csv（看上面命令） - 从 Excel 导出时选 "CSV UTF-8 (Comma delimited) (.csv)"，不是普通 "CSV"
- 日期混乱：Excel 里把列格式统一为
yyyy-mm-dd再导 - 体量过大：用
split -l 5000 data.csv chunk_分块 - 导入向导第 2 步可以手动指定每列类型 — 不要依赖自动识别
应急方案
如果导入怎么都搞不定，可以新建一张空表、手动设字段类型、然后从 CSV 复制粘贴行进表 — Kition 数据表支持从剪贴板批量粘贴（Cmd/Ctrl + V），它会按表头智能映射。
另一个救场办法：用 Pandas、jq 或任意脚本把 CSV 转成 JSON / NDJSON，Kition 有 "Import from JSON" 入口，对脏数据宽容得多。
什么时候该提 bug
- UTF-8 + 标准 CSV + < 1000 行仍导入失败
- 导入按钮点了没反应、日志也没新行 — UI 事件没派发
- 日期格式严格 ISO 8601，仍被识别成文本
- 大文件分块导入时 Kition 卡死或 OOM