xlsx库解析Excel时中文乱码如何解决？

Question

使用 xlsx 库（如 Node.js 中的 `xlsx` 或 Python 中的 `openpyxl`）解析 Excel 文件时，中文出现乱码的常见原因是文件编码或读取方式未正确处理 Unicode 字符。尤其当 Excel 文件以二进制格式（如 .xls）保存或未明确指定编码时，库可能默认使用 ASCII 或其他非 UTF-8 编码解析文本，导致中文字符显示为乱码。此外，部分库在处理流式数据或 Buffer 时若未设置正确的字符集选项，也会引发该问题。如何确保 xlsx 库正确识别和解析包含中文的单元格内容？

Answer 1

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

在使用 xlsx（Node.js）或 openpyxl（Python）解析 Excel 文件时，中文内容常表现为如下乱码形式：

• 柳市人民银行
• ????
• 北京（未解码的 HTML 实体）

这类问题多出现在以下场景中：

1. 读取 .xls 格式文件（二进制格式，非 XML）
2. 通过 HTTP 请求流式读取远程 Excel 文件
3. 处理 Buffer 数据而未指定编码类型
4. 跨平台传输中字符集转换丢失

根本原因通常并非库本身缺陷，而是数据输入阶段未正确识别 Unicode 编码。

2. 深入分析：Excel 文件格式与编码机制

文件扩展名	格式标准	编码支持	典型解析库
.xlsx	Office Open XML (ECMA-376)	UTF-8 内嵌于 ZIP 容器中	xlsx, openpyxl
.xls	Binary Interchange File Format (BIFF)	可包含 Code Page 或 Unicode 记录	xlsx, xlrd
.csv (with .xls)	文本格式伪装为 Excel	依赖 BOM 或显式声明编码	pandas, fs + xlsx

关键点在于：.xlsx 文件本质上是 ZIP 压缩包，其内部 XML 文件默认采用 UTF-8 编码；而 .xls 是二进制结构，可能使用 ANSI、Shift-JIS 或 UTF-16LE 等编码方式存储字符串记录。若解析器未能自动检测或强制设定编码，则中文极易出现乱码。

3. Node.js 中 xlsx 库的正确使用方式

以 SheetJS/js-xlsx 为例，确保中文正常显示的关键在于：

const XLSX = require('xlsx');
const fs = require('fs');

// 方式一：直接读取文件（推荐）
const workbook = XLSX.readFile('chinese_data.xls', {
  type: 'file',
  codepage: 65001  // 显式指定 UTF-8
});

// 方式二：处理 Buffer（如从网络请求获取）
const buffer = fs.readFileSync('chinese_data.xlsx');
const workbookFromBuf = XLSX.read(buffer, {
  type: 'buffer',
  encoding: 'utf-8'
});

// 提取数据并验证中文
const sheetName = workbook.SheetNames[0];
const worksheet = workbook.Sheets[sheetName];
const jsonData = XLSX.utils.sheet_to_json(worksheet, { header: 1 });
console.log(jsonData[0]); // 应正确输出 ['姓名', '城市'] 而非乱码

注意：codepage: 65001 是 Windows 下对 UTF-8 的标识，能有效提升对旧版 .xls 文件中宽字符的支持。

4. Python 中 openpyxl 与编码兼容性处理

openpyxl 专为 .xlsx 设计，默认支持 UTF-8，但仍需注意上下文环境：

import openpyxl
from io import BytesIO
import requests

# 场景：从 URL 流式加载 Excel 文件
response = requests.get("https://example.com/data.xlsx")
response.raise_for_status()

# 必须使用 BytesIO 包装二进制内容
workbook = openpyxl.load_workbook(BytesIO(response.content))
sheet = workbook.active

for row in sheet.iter_rows(values_only=True):
    print(row)  # 正确输出中文如 ('张三', '北京')

若误将字节流当作文本流处理（例如使用 StringIO），则必然导致解码错误。务必保证在整个 I/O 链路中保持二进制透明传输。

5. 综合诊断流程图

graph TD A[开始解析Excel] --> B{文件格式?} B -- .xlsx --> C[使用openpyxl/XLSX.read] B -- .xls --> D[检查是否含BOM/CodePage] C --> E[确认输入为Buffer/Binary] D --> F[设置codepage=65001或type=buffer] E --> G[提取单元格值] F --> G G --> H{存在乱码?} H -- 是 --> I[检查系统locale及终端编码] H -- 否 --> J[成功解析中文] I --> K[重试并强制UTF-8解码]

6. 高级建议与最佳实践

• 统一使用 .xlsx 格式替代 .xls，避免 BIFF 编码歧义
• 在服务端处理前，可通过 file 命令检测文件实际类型：file --mime-type your_file.xls
• 对于上传接口，设置 Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• 使用 chardet（Python）或 detect-character-encoding（Node.js）预判编码
• 日志输出时确保控制台支持 UTF-8（Linux/macOS 一般无问题，Windows 需设置 chcp 65001）
• 测试用例应包含常用中文字符集：简体、繁体、emoji（如 🇨🇳）
• 考虑使用 pandas.read_excel() 作为封装层，其底层已集成多种引擎容错机制
• 对老旧系统导出的 Excel，建议先用 LibreOffice 批量转存为标准 .xlsx
• 部署环境中设置环境变量 LANG=zh_CN.UTF-8 可减少潜在编码冲突
• 前端导出时添加 BOM 头（\ufeff）有助于 Excel 正确识别 UTF-8