PhpSpreadsheet读取Excel转数组时中文乱码如何解决？

Question

在使用PhpSpreadsheet读取Excel文件并转换为数组时，部分中文内容出现乱码（如显示为“？？”或特殊符号），尤其是在处理CSV文件或非UTF-8编码的Excel文件时更为常见。该问题通常源于文件原始编码未被正确识别，或服务器环境缺少对Unicode的支持。尽管PhpSpreadsheet默认支持UTF-8，但在加载文件时若未显式指定编码或使用了不兼容的读取方式，仍会导致中文字符解析错误。如何确保PhpSpreadsheet正确识别并读取含中文的Excel数据，避免数组中出现乱码，是开发者常遇到的技术难题。

Answer 1

1. 乱码问题的表层现象与常见场景

在使用 PhpSpreadsheet 处理包含中文内容的 Excel 或 CSV 文件时，开发者常遇到中文字符显示为“？？”或特殊符号的问题。这一现象多出现在以下场景：

• 上传的文件由 Windows 系统下的 WPS 或 Excel 导出，默认编码为 GBK 或 GB2312
• CSV 文件未明确声明 UTF-8 BOM 头
• 服务器环境未启用 mbstring 扩展或 locale 设置不支持 Unicode
• 前端通过 HTTP POST 上传文件时未正确处理 Content-Type 编码

尽管 PhpSpreadsheet 内部默认使用 UTF-8 编码进行数据解析和输出，但若原始文件并非 UTF-8 格式，则读取过程中将无法正确映射字节流到对应的 Unicode 字符，从而导致解码失败。

2. 编码机制深度剖析：从字节流到字符映射

理解乱码本质需深入字符编码转换过程。Excel 文件（如 .xlsx）本质上是 ZIP 压缩包，内部 XML 文件通常以 UTF-8 存储；而 .xls 和 CSV 则可能采用系统默认编码（如 CP936/GBK）。

文件类型	常见编码格式	PhpSpreadsheet 默认行为
.xlsx	UTF-8（带BOM可选）	自动识别，一般无问题
.xls	UTF-16LE / CP1252	依赖 Reader 配置
CSV	GBK, GB2312, ANSI	需手动设置输入编码

当输入流的编码与解析器预期不符时，PHP 的字符串处理函数（如 substr、json_encode）会因无效 UTF-8 序列返回替代字符（），最终表现为“？？”。

3. 解决方案层级一：配置正确的文件读取方式

对于 CSV 文件，必须显式指定输入编码。可通过 Csv 类的 setInputEncoding 方法实现：

$reader = new \PhpOffice\PhpSpreadsheet\Reader\Csv();
$reader->setInputEncoding('GBK'); // 针对中文Windows导出文件
$reader->setDelimiter(',');
$reader->setEnclosure('"');
$spreadsheet = $reader->load($filename);
$data = $spreadsheet->getActiveSheet()->toArray();

若不确定原始编码，可结合 mb_detect_encoding 进行初步判断：

$content = file_get_contents($filename);
$encoding = mb_detect_encoding($content, ['UTF-8', 'GBK', 'GB2312'], true);
if ($encoding !== 'UTF-8') {
    $content = mb_convert_encoding($content, 'UTF-8', $encoding);
}
// 再写入临时文件供 PhpSpreadsheet 读取

4. 解决方案层级二：环境与扩展支持优化

确保服务器具备完整的多字节字符串处理能力至关重要。检查以下 PHP 配置项：

• extension=mbstring 是否启用
• default_charset = "UTF-8" 是否设置
• mbstring.internal_encoding = UTF-8
• Linux 系统建议设置 locale：export LC_ALL=zh_CN.UTF-8

此外，在 Nginx/Apache 中应添加响应头以统一传输编码：

add_header Content-Type "text/html; charset=utf-8";

5. 高级策略：构建智能编码探测管道

为应对多样化的用户上传文件，可设计自动化编码识别流程：

graph TD A[接收上传文件] --> B{文件扩展名?} B -->|CSV| C[读取前1KB内容] B -->|.xls/.xlsx| D[交由对应Reader解析] C --> E[调用mb_detect_encoding] E --> F[尝试GBK/GB2312/BIG5] F --> G[转换为UTF-8临时文件] G --> H[使用Csv Reader加载] D --> I[直接toArray()] H --> J[合并结果数组] I --> J J --> K[输出标准化UTF-8数组]

6. 实际案例中的容错处理模式

在企业级应用中，建议封装一个健壮的数据导入服务类：

class ExcelImporter
{
    public function import($filePath): array
    {
        $info = pathinfo($filePath);
        $reader = match(strtolower($info['extension'])) {
            'csv' => $this->createCsvReader($filePath),
            'xls' => new \PhpOffice\PhpSpreadsheet\Reader\Xls(),
            'xlsx' => new \PhpOffice\PhpSpreadsheet\Reader\Xlsx(),
            default => throw new InvalidArgumentException("Unsupported file type")
        };

        try {
            $spreadsheet = $reader->load($filePath);
            return $this->sanitizeArray($spreadsheet->getActiveSheet()->toArray());
        } catch (\PhpOffice\PhpSpreadsheet\Reader\Exception $e) {
            error_log("Spreadsheet read error: " . $e->getMessage());
            throw $e;
        }
    }

    private function createCsvReader($filePath): \PhpOffice\PhpSpreadsheet\Reader\Csv
    {
        $reader = new \PhpOffice\PhpSpreadsheet\Reader\Csv();
        $sample = file_get_contents($filePath, false, null, 0, 1024);
        $encoding = mb_detect_encoding($sample, ['UTF-8', 'GBK', 'GB2312', 'BIG5'], true);
        $reader->setInputEncoding($encoding ?? 'UTF-8');
        $reader->setDelimiter($this->detectDelimiter($sample));
        return $reader;
    }

    private function sanitizeArray(array $data): array
    {
        array_walk_recursive($data, function (&$item) {
            if (is_string($item)) {
                $item = mb_convert_encoding($item, 'UTF-8', mb_detect_encoding($item, 'auto', true));
            }
        });
        return $data;
    }
}