xlrd离线安装后无法读取xlsx文件？

Question

问题：使用xlrd进行离线安装后，程序在读取.xlsx格式文件时抛出“NotImplementedError: only support .xls files”错误。这是因为xlrd从2.0版本开始移除了对Excel 2007及以上版本（即.xlsx）的支持，仅支持旧的.xls格式。许多用户在离线环境中误装了新版xlrd，却未意识到其不再支持xlsx文件，导致解析失败。该问题常见于无法联网、依赖本地包部署的内网环境，且缺乏对版本兼容性的提示，排查困难。

Answer 1

一、问题背景与现象分析

在使用Python进行Excel文件处理时，xlrd库曾是广泛采用的工具之一。然而，自其2.0版本起，官方移除了对.xlsx格式的支持，仅保留对旧版.xls（二进制格式）文件的读取能力。这一变更导致许多开发者在离线环境中部署程序后，遇到如下异常：

NotImplementedError: only support .xls files

该错误通常出现在以下场景中：

• 内网或隔离环境下的离线安装包管理；
• 未明确指定依赖版本，导致自动安装最新版xlrd；
• 开发与生产环境使用的xlrd版本不一致；
• 缺乏对第三方库变更日志的关注和版本锁定机制。

由于缺少清晰的运行时提示或文档指引，排查此类问题往往耗时较长，尤其在无法联网查看更新说明的封闭系统中更为棘手。

二、技术演进与版本变迁

xlrd版本	发布时间	支持文件类型	关键变化
< 2.0	2019年及以前	.xls 和 .xlsx	通过内部解析器支持Office Open XML
≥ 2.0	2020年后期	仅 .xls	移除xlsx支持，提升安全性和维护性
2.3.0（最新稳定版）	2023年	仅 .xls	持续维护.xls读取功能

三、根本原因剖析

从源码层面看，xlrd在v2.0之后删除了对ZIP压缩结构和XML解析的相关模块。当尝试打开.xlsx文件时，会触发如下逻辑判断：

if file_contents[0:8] != b'\x50\x4B\x03\x04\x14\x00\x06\x00':
        raise NotImplementedError("only support .xls files")

其中\x50\x4B...是ZIP文件头标识，而.xlsx本质上是一个ZIP压缩包，包含多个XML组件。一旦检测到该头信息但库本身不具备解压与解析能力，则直接抛出异常。

四、解决方案全景图

针对不同运维策略和技术栈，可采取以下多种应对方式：

1. 降级xlrd至1.2.0版本：适用于需保持原有代码结构不变的项目。
2. 迁移到openpyxl库：推荐用于新项目或重构场景，原生支持.xlsx且功能更强大。
3. 使用pandas结合指定引擎：通过pd.read_excel(engine='openpyxl')实现无缝过渡。
4. 构建私有PyPI仓库并锁定依赖版本：防止未来再次误装不兼容版本。
5. 引入dependency management工具如pip-tools或Poetry，确保环境一致性。
6. 编写兼容性检测脚本，在启动时验证库版本与文件类型的匹配性。

五、迁移示例与代码实践

原始出错代码：

import xlrd
workbook = xlrd.open_workbook('data.xlsx')  # 抛出 NotImplementedError

修改为使用openpyxl的正确做法：

from openpyxl import load_workbook
workbook = load_workbook('data.xlsx')
sheet = workbook.active
for row in sheet.iter_rows(values_only=True):
    print(row)

六、架构级预防机制设计

为避免类似问题在企业级系统中反复出现，建议建立如下流程：

graph TD
            A[需求开发] --> B{是否涉及Excel处理?}
            B -- 是 --> C[明确文件格式:xls/xlsx]
            C --> D[选择对应解析库]
            D --> E[在requirements.txt中固定版本]
            E --> F[CI/CD流水线执行兼容性测试]
            F --> G[部署至内网环境前进行沙箱验证]
            G --> H[上线运行]
            B -- 否 --> I[正常流程继续]

七、最佳实践总结清单

• 永远不要在生产环境中使用pip install xlrd而不指定版本；
• 对于.xlsx文件，优先选用openpyxl或xlswriter；
• 在requirements-offline.txt中显式声明xlrd==1.2.0（若必须用）；
• 添加单元测试覆盖不同Excel格式的读取场景；
• 定期审查第三方库的弃用通知与安全公告；
• 为关键服务编写“依赖健康检查”中间件；
• 培训团队成员理解常见库的历史演变与限制；
• 建立内部知识库记录典型坑点与修复方案；
• 利用Docker镜像固化运行环境，减少差异；
• 监控日志中是否频繁出现NotImplementedError相关堆栈。