禅道导出CSV乱码：UTF-8 BOM与Excel兼容修复方案

上周帮一位做实施的朋友处理一个挺尴尬的现场：他在会议室投屏演示，点下禅道导出按钮，CSV 文件用 Excel 一打开，满屏的“锟斤拷”和“涓枃”。会议室安静了三秒，甲方问了一句“你们这系统是不是有问题”。其实系统没坏，数据一个字都没丢，问题出在“文件是 UTF-8 编码，Excel 却按 GBK 去读”这件小事上。

禅道导出文件乱码是项目管理工具落地过程中出现频率极高、但修复成本极低的一类问题。它影响的环节比想象中广：不只是自己看一眼报表，还包括把数据交给下游做对账、把工单清单存档、把任务表导入另一个系统做二次加工。一旦乱码，整条数据交接链就断了。这篇内容面向三类人：用工具的业务同事（学会不改代码的应急处理）、负责二次开发的工程师（掌握代码层的根治方案）、以及做实施和运维的同学（搞清楚全局编码一致性）。我会把症状分类、根因定位、代码改法、用户侧救急、全局排查这五块讲透，参数和命令都给到能直接抄的程度。

1. 先把“乱码”这件事看清楚：症状分类与根因定位

1.1 三种典型乱码现场，对应三种完全不同的病因

很多人一看到乱码就认定是“编码不统一”，然后把所有能转码的工具试一遍，结果越转越乱。实际上乱码有明确的分型，看字符长相基本就能锁定方向。

第一种，中文变成一堆问号???或者空白方块。这是“目标编码表里没有这个字”导致的不可逆丢失，常见于把 UTF-8 硬转成 GBK 或 ASCII 时碰到了生僻字、异体字、emoji。注意关键词是“不可逆”——原文件已经被写坏了，只能重新导出，不能靠再转一次修回来。

第二种，中文变成“涓枃”“鐠囧瓨”这类看着像繁体又不像繁体、笔画繁复的怪字符。这是最典型的“UTF-8 字节流被当成 GBK 解码”。拿“中文”两个字举例，UTF-8 下是E4 B8 AD E6 96 87六个字节，两两一组按 GBK 去解，就变成“涓枃”。这类乱码是可逆的，转回去能还原。

第三种，中文变成ä¸Â这种带重音字母的西欧字符。这是 UTF-8 被当成 Latin-1 或 Windows-1252 解读，属于“双重编码”，常见于文件经过了一次错误的转码又保存。

还有一种容易被误判的：数字变成1.23457E+17，工单号、身份证号末尾变 000。这根本不是编码问题，是 CSV 里长数字被 Excel 当数值处理了。搞清楚这一点能省下大量瞎折腾的时间。

1.2 编码在导出链路里到底经过了几次转折

要根治，得先知道字符从数据库到你屏幕上一共走了几步。禅道这类 PHP 系项目管理工具，导出 CSV 的链路大致是：数据库按连接字符集取出数据，PHP 在内存里拼成字符串（此时是 UTF-8），写入临时文件或直接输出到响应流，浏览器按响应头下载，最后由 Excel 打开。

问题就出在最后一步。CSV 是纯文本格式，规范里没有规定“文件必须带编码声明”，也不像 HTML 有<meta charset>，也不像 XML 有<?xml encoding?>。Excel 打开一个无 BOM 的 CSV 时，会退回到系统默认的 ANSI 代码页。简体中文 Windows 的 ANSI 代码页是 936，也就是 GBK 系。而禅道输出的内容编码是 UTF-8。中间没有任何协商环节，Excel 就用 GBK 的规则去切 UTF-8 的字节，于是乱码必然发生。

这里有个细节值得强调：同一份文件，用记事本打开可能是正常的，用 Excel 打开就是乱的。原因在于记事本会做编码嗅探，检测到合法的 UTF-8 序列就按 UTF-8 显示；Excel 是老派的“信系统不信文件”。所以“我记事本打开没问题”这句话，不能作为“文件没问题的证据”。

影响范围也在这里显现：如果这份 CSV 是给下游系统做批量导入用的，对方的解析程序如果默认按 UTF-8 读，反而一切正常；反而是人工用 Excel 打开检查的那一步出了岔子。搞清楚“谁在消费这个文件”，决定了你应该往哪个方向修。

2. 从代码层解决：改导出逻辑的几种做法与取舍

2.1 成本最低的一招：给 CSV 补上 UTF-8 BOM

BOM 是 Byte Order Mark 的缩写，UTF-8 的 BOM 是固定的三个字节EF BB BF。它的作用是给文件开头盖一个戳，告诉读取方“我是 UTF-8”。Excel 认这个戳，看到就老老实实按 UTF-8 解析。

改法非常轻。找到导出逻辑里创建文件句柄的那几行，在写入任何内容之前，先把这三个字节塞进去。PHP 下的写法：

$fp = fopen($filePath, 'w'); // 必须在写入任何内容之前，只写一次 fwrite($fp, "\xEF\xBB\xBF"); fputcsv($fp, $headerRow);

如果你改的是直接输出到浏览器的分支，就是：

echo "\xEF\xBB\xBF"; // 后面再输出 CSV 内容

关键点有三个。第一，BOM 必须是文件的第一个字节，写在中间等于污染数据。第二，只能写一次，循环里写会产出一堆EF BB BF。第三，改完记得清一下临时文件缓存——有些实现会把导出结果缓存到临时目录，你不清缓存，改完代码测出来还是乱的，白白怀疑人生。

这招的优点是改动量只有一行，风险极低，不需要动数据库、不需要加依赖。缺点也很明确：BOM 会把某些严格的解析器搞晕。Python 的csv模块用encoding='utf-8'打开带 BOM 的文件，第一列列名会变成\ufeff姓名，必须改用utf-8-sig。Node 的一些 CSV 库同理。所以如果你的导出文件同时要给程序消费，加 BOM 之前先跟对接方确认一句，避免按下葫芦浮起瓢。

2.2 面向 Excel 的妥协：转成 GBK 输出

另一种思路是顺着 Excel 的脾气来：既然你按 GBK 读，那我就按 GBK 写。在输出前把整段内容转码：

$content = mb_convert_encoding($content, 'GB18030', 'UTF-8');

这里我特意用了GB18030而不是GBK。GB18030 是 GBK 的超集，能覆盖绝大部分汉字，包括 GBK 表达不了的扩展区字符。用GBK转生僻字会直接变成问号，而且不可逆。

如果你用的是iconv，要加忽略标记避免整段转换中途失败：

$content = iconv('UTF-8', 'GB18030//IGNORE', $content);

//IGNORE的语义是遇到转不了的字符就跳过，代价是那部分字符彻底消失。我个人更推荐//TRANSLIT，它会尝试用近似字符替代，虽然结果不一定好看，但至少不会凭空吞数据。

这条路的风险点必须说清楚：GB18030 依然表达不了 emoji 和部分少数民族文字、特殊符号。如果你的任务标题里有人喜欢打表情符号，转码后这些位置会变成问号，而且没有任何报错提示，属于静默数据损坏。所以我通常的建议是——如果这个导出文件只给人看、只给 Excel 看，用 GB18030；如果还要进系统，老老实实加 BOM 保持 UTF-8。

2.3 从 CSV 升级到真正的 Excel 文件

治本的做法是别再用 CSV 糊弄人，直接生成.xlsx。xlsx 本质是个 zip 包，内部 XML 明确声明了编码，不存在“猜编码”这回事，中文、emoji、生僻字全都稳。同时还能顺手解决长数字被转科学计数法、前导零丢失这些 CSV 时代的老毛病。

PHP 生态里主流是 PhpSpreadsheet。核心逻辑就三步：建工作簿、逐行写单元格、保存。写单元格时把值当字符串处理，长数字列显式设置成文本格式：

$sheet->setCellValueExplicit('B'.$row, $orderNo, \PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_STRING);

但这套方案不是没代价，选型时要算三笔账。

第一笔是内存。PhpSpreadsheet 每个单元格对象都有不小的开销，几千行还行，几万行往上就容易撞 PHP 的memory_limit。解决办法是分批写、及时unset、或者上OpenSpout这类流式写入库。第二笔是行数上限，xlsx 单表上限 1048576 行，超过就得考虑分 sheet 或分文件——不过真到这个量级，导出本身就该改成异步任务了。第三笔是依赖维护，引入一个库意味着后续升级要跟着走，老环境里的 PHP 版本可能不满足新版本库的要求。

我的取舍原则很朴素：导出量在万行以内、且主要是给人看，直接上 xlsx；导出量巨大、且下游是程序消费，保持 CSV + UTF-8 BOM。别为了“看起来高级”给服务器找麻烦。

2.4 版本差异带来的坑：导出入口不是一个地方

改代码之前还有个前置动作容易漏——先确认你改的那个文件，是不是真的在被执行。禅道经历过多次重构，导出功能的实现位置在不同版本之间搬过家。有的版本走独立的导出控制器，有的版本把导出逻辑塞在列表页的同一个控制器里靠参数区分，还有的版本把 CSV 生成抽成了公共方法，被多个模块共用。

如果你改完没效果，别急着怀疑自己的代码，按这个顺序验证：先在疑似文件里加一行error_log('hit')或临时exit('here')，点一次导出，看日志或页面有没有反应。有反应说明找对了，没反应说明这个入口没被走到。这一步能省掉大量“改了半小时其实改的是废弃文件”的时间。

另外一个常被忽视的点：如果站点开了 opcache，改完 PHP 文件可能不生效。清一下 opcache 或者重启 PHP-FPM 再测。我见过有人因为没清缓存，把“加 BOM 无效”这个结论写进了工单，最后发现是自己没重启。

3. 不改代码的应急方案：给业务同事的救火手册

3.1 Excel 导入向导里的编码选择，两分钟解决

现场演示、客户催报表的时候，你没有权限改代码，也没有时间走发布流程。这时候最快的路是在 Excel 侧解决。

老版本 Excel 的路径是：数据 → 自文本 → 选中文件 → 第一步的“文件原始格式”下拉里选65001 : Unicode (UTF-8)→ 分隔符号勾逗号 → 列数据格式把长数字列设成文本 → 完成。

新版本（Office 365、2016 以后）路径变成：数据 → 从文本/CSV → 选文件 → 弹出的预览窗口里有个“文件原始格式”，从“936 : GB2312”改成65001 : Unicode (UTF-8)→ 加载。

注意那个“65001”不是随便编的数字，它是 UTF-8 的代码页编号，Excel 内部就靠这个数字认编码。记不住也没关系，下拉框里选带“Unicode (UTF-8)”字样的那一项就行。

这条路的好处是不动任何代码、不惊动任何人。缺点是每次导出都得重来一遍，导十个文件就要点十次。所以它只适合应急，不适合当长期方案。

另外提醒一句：如果你的 Excel 打开导入向导后，预览里中文已经是正常的了，但点“加载”之后又乱了，那多半是列类型推断的问题，而不是编码问题。在预览窗口里把相关列的类型手动改成“文本”再加载。

3.2 本地转码：记事本、编辑器和命令行三件套

如果文件已经导出，手上只有 Excel 和记事本，最土但最有效的办法是：用记事本打开 CSV → 文件 → 另存为 → 编码选ANSI→ 保存 → 再用 Excel 打开。记事本会先按 UTF-8 正确读出内容，再按你指定的 GBK 写回去，等于做了一次人工转码。同一份文件记得换个文件名，别把原始文件覆盖掉，万一转错了还得重导。

有 Notepad++ 的话更顺手：打开文件（如果显示乱码，先点“编码 → 转为 UTF-8”把显示修正）→ 编码 → 转为 ANSI 编码 → 保存。VS Code 也可以，右下角点当前编码 → 通过编码保存 → 选GB18030。VS Code 的“通过编码重新打开”和“通过编码保存”是两个不同操作，前者只改显示、后者才真正落盘，这一点很多人搞混。

Linux 服务器上就更直接了，两条命令：

# 查看文件真实编码 file -i export.csv # 查看开头三个字节，有没有 BOM 一眼可见 head -c 3 export.csv | xxd

efbb bf就是 BOM。转码用：

iconv -f UTF-8 -t GB18030 export.csv -o export_gbk.csv

反过来，如果收到一份 GBK 文件要转 UTF-8 给系统用：

iconv -f GB18030 -t UTF-8 export.csv -o export_utf8.csv

如果要顺手加上 BOM：

printf '\xEF\xBB\xBF' > out.csv && cat export.csv >> out.csv

反过来要去掉别人给的 BOM：

sed -i '1s/^\xEF\xBB\xBF//' export.csv

这几条命令我放在备忘录里好几年了，处理对接方发来的奇怪文件特别管用。

3.3 别忽略下载环节：文件名乱码和内容乱码是两码事

有个现象经常被混为一谈：文件内容打开是对的，但下载下来的文件名是一串%E4%BB%BB%E5%8A%A1或者干脆显示成乱码方块。

这跟 CSV 内容编码没关系，问题在 HTTP 响应头。Content-Disposition里的filename参数按老规范只允许 ASCII，直接把中文塞进去，不同浏览器处理方式不一样，有的按 Latin-1 解，有的直接丢弃。

规范做法是双写，老参数给rawurlencode后的值，新参数用filename*声明编码：

$name = rawurlencode($fileName); header("Content-Disposition: attachment; filename=\"{$name}.csv\"; filename*=UTF-8''{$name}.csv");

filename*的语法是编码''URL编码后的名字，中间的''是两个单引号，分别代表 charset 和 language，language 留空。这个格式是 RFC 5987 定的，主流浏览器都认。

排查顺序上我建议先分清楚：内容是乱的，还是名字是乱的，还是两者都乱。内容乱看编码，名字乱看响应头，两者都乱往往是同一个根因的两种表现，先把内容修好，名字问题再单独处理。

4. 全局编码一致性检查：别只盯着导出那一行

4.1 数据库连接字符集：数据源头就错了的话，导出怎么改都没用

有一种情况特别迷惑人：你明明加了 BOM，导出文件在 Excel 里显示正常了，但仔细一看，某些字段里的中文从源头上就是乱的，或者问号。这时候问题不在导出，在入库。

判断方法很直接：在系统页面上看这条记录显示是否正常。如果页面显示就是乱的，那说明数据在写入数据库时就已经坏了，导出环节只是把坏数据原样搬出来。这种情况下改导出代码属于南辕北辙。

检查方向有这么几个。一是连接字符集，PHP 连 MySQL 时如果没有显式设置字符集，可能走服务器默认值，早期默认值有latin1的情况。二是表的字符集，如果表是utf8（MySQL 里这个 utf8 只支持 3 字节，存不了 4 字节的 emoji），写入 emoji 时会被截断或报错。三是字段本身的排序规则。

顺带解释一下utf8和utf8mb4的区别，这个概念坑过太多人。MySQL 的utf8是个历史遗留命名，实际只支持最多 3 字节，覆盖基本多文种平面；utf8mb4才是完整的 4 字节 UTF-8。任务标题、项目描述里只要有人打了 emoji，用utf8的表就会出现截断——而且截断位置在 emoji 之前，后面的内容全丢，非常隐蔽。

改表字符集的动作比较重，涉及锁表和备份，生产环境要慎之又慎，我一般不轻易建议动它。更现实的做法是：新表直接用utf8mb4，老表如果问题不严重就用应用层过滤 emoji 兜住。

4.2 响应头和页面编码：一致性的最后一公里

除了 CSV 导出，还有一种乱码发生在“把导出的 HTML 表格直接粘到 Excel”这条路上。有些人嫌 CSV 麻烦，直接在列表页全选复制，粘到 Excel 里，发现中文变乱码。这时候的原因跟 CSV 完全不同，是剪贴板传递和 Excel 粘贴时的编码解释问题。

稳妥做法还是走标准导出。如果确实需要 HTML 表格，导出文件里最好带上一段声明：

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

同时在响应头里写Content-Type: text/html; charset=utf-8。两处都写不是冗余，是兼容——有些读取方只看头，有些只认文件内的声明。

这里有个经验：排查编码问题时，我习惯一次性把所有相关位置的编码都打印出来对照，包括文件字节、响应头、文件内声明。三者一致，问题基本就没了。三者不一致的时候，往往是历史改动留下的坑，改了一处忘了另一处。

4.3 临时目录与文件权限：导出为空、导出卡住的另一种“乱”

还有一种情况被误归到乱码里：导出点了没反应，或者下载下来是个 0 字节的空文件，或者只有表头没有数据。

这类问题跟编码无关，多半是临时目录的问题。导出量大的时候，程序通常会先把内容写到临时文件，再整体输出。如果临时目录不可写、磁盘满了、或者 PHP 的open_basedir限制导致无法访问，就会出现“流程走完但文件是空的”。

排查动作有三个。一看临时目录权限，跑 PHP 的那个用户对目录有没有写权限。二看磁盘空间，df -h一下，这个我踩过，磁盘写满之后表现就是各种莫名其妙的导出失败。三看 PHP 错误日志，open_basedir限制、内存超限、执行超时都会在那里留痕。

内存和执行时间这两项也值得单独提。导出几万行数据时，PHP 默认的memory_limit很容易不够，表现是页面白屏或者导出中途截断，截断的位置往往在文件中间，看起来像是文件损坏。加大memory_limit和max_execution_time能缓解，但更彻底的做法是把大导出改成异步任务，后台生成、生成完给个下载链接。这个改造量不小，但一旦导出量上万，早晚要做。

5. 常见问题速查与排错实录

5.1 一张表把主要症状和处置方式对齐

下面这张表是我这些年攒下来的对照表，遇到问题基本能三分钟内定位方向。表格里的“验证方式”一列很关键，先验证再动手，别凭感觉改。

这张表有两行值得单独展开。一是“长数字变科学计数法”，这个太常见了，工单号、批次号、手机号中招率极高，而且它伪装成编码问题，让人往错的方向修。二是“表头正常数据行少一半”，典型的分批写入出错或者内存爆掉，看到这种就要立刻想到资源限制。

5.2 几个踩过的坑和现场处置记录

坑一：改了公共导出方法，结果影响了别的模块。有一次我给导出方法统一加了 BOM，结果另一个本来给程序消费的导出功能也带上了 BOM，对方的 Python 脚本读进去第一列列名多了个不可见字符，对账直接对不上。教训是：改公共方法之前先搜一遍调用点，看看有没有程序消费方。要么加参数控制是否输出 BOM，要么只改特定模块的实现。

坑二：GBK 转码吞掉了 emoji，全程没报错。某项目导出的任务清单里，标题带表情符号的那几十条记录，字符全变成问号。因为转码函数用了//IGNORE，悄无声息就丢数据了。后来改成先检测有没有 4 字节字符，有就提示用户“含有特殊字符，建议使用 UTF-8 导出”。这个提示看着多余，但确实挡住了数据丢失。

坑三：以为改了代码，其实改的是缓存副本。有些部署结构下，工作目录和实际运行目录是分开的，你改了 A 目录，跑的是 B 目录。加个error_log验证，比反复揣测靠谱得多。

坑四：Excel 版本差异导致同一份文件两台电脑表现不同。同一份带 BOM 的 CSV，一台打开正常，另一台打开第一列列名前面有个古怪符号。原因是新版 Excel 处理 BOM 更规范，老版本会把 BOM 当成数据。这种情况没有完美解，只能按主要使用人群的 Excel 版本选方案。

坑五：清了浏览器缓存，忘了清服务端缓存。导出结果被缓存到临时目录，改代码后第一次点导出，拿到的还是旧文件。加上文件 mtime 校验或者手动清空临时目录，问题消失。

坑六：跨平台换行符导致的解析异常。Linux 生成的 CSV 是 LF 换行，某些老系统按 CRLF 解析，读出来是一整行。用unix2dos转一下就好，但如果下游对接方的文档没写清楚，这个坑能排查一整天。我现在的习惯是，对外交付的 CSV 一律转成 CRLF，接受方大多在 Windows 上。

我在实际操作中的体会是，编码问题之所以让人烦躁，不是因为难，而是因为“看不见”。字节层面发生了什么，肉眼完全无从判断，只能靠工具和方法一点点逼近真相。所以我形成了一个固定习惯：遇到任何乱码，先做三件事——用file -i看编码、用head -c 3看 BOM、用十六进制看一段中文字节。这三步做完，问题基本就锁定在某个具体环节了，剩下的只是按图索骥。

最后分享一个小技巧。如果你经常要在客户现场处理这类问题，手边备一个能十六进制查看的编辑器，比什么都管用。Excel 说文件乱码，记事本说文件正常，两个软件吵架的时候，字节才是唯一的事实。