Python升级后openpyxl图表不显示？教你完美解决

2025-03-25 20:04:29

Python 版本升级后，openpyxl 生成的图表不显示了？教你搞定！

不少朋友可能遇到过这样的怪事：用 Python 3.7 配合 openpyxl 生成带图表的 Excel 文件，一切正常，图表漂漂亮亮。可一旦把 Python 升级到 3.8 或更高版本（比如 3.10, 3.11, 甚至 3.13），同样的代码生成的 Excel 文件里，图表就“翻车”了——要么显示不全，要么样式错乱，甚至干脆一片空白。

就像下面这样：

Python 3.7 + openpyxl 生成的正常图表：
Python 3.8+ + openpyxl 生成的异常图表：

这到底是咋回事呢？

问题根源探究

有朋友经过一番搜索和尝试，发现了一个有趣的线索。问题的关键似乎藏在生成的 .xlsx 文件内部的一个叫做 app.xml 的文件里。

.xlsx 文件本质上是一个 ZIP 压缩包。解压后，可以在 docProps 目录下找到 app.xml。对比 Python 3.7 和更高版本生成的 app.xml，会发现一个差异：

高版本 Python + openpyxl 生成的 app.xml 文件里，<Application> 标签的内容是 "Compatible / Openpyxl"。
而 Python 3.7 + openpyxl 生成的文件里，这个标签的内容可能只是 "Microsoft Excel" 或其他，但没有 "Compatible / Openpyxl" 这部分。

app.xml 文件对比

神奇的是，如果手动修改高版本生成的 .xlsx 文件（先改成 .zip 后缀，解压，编辑 docProps/app.xml，去掉 "Compatible / Openpyxl" 字样，再压缩回去，改回 .xlsx 后缀），图表竟然又能正常显示了！

这说明，"Compatible / Openpyxl" 这个标记似乎在高版本 Python 环境下，以某种方式干扰了 Excel 或其他兼容软件（如 WPS Office, LibreOffice）对图表的正确渲染。具体原因可能是：

标记误导： 这个标记可能暗示 Excel 使用某种兼容模式来打开文件，而这种模式恰好与 openpyxl 新版本生成的图表定义方式不兼容。
库版本与标记： openpyxl 库本身在更新过程中，可能改变了生成图表对象所依赖的底层 XML 结构或命名空间。同时，它又添加了 "Compatible / Openpyxl" 标记。这两者的组合在高版本 Python 环境下（可能影响了某些依赖库的行为）导致了渲染问题。
Excel 渲染差异： 不同版本的 Excel 或其他电子表格软件对这个标记的解释和处理可能存在差异。

虽然根本原因错综复杂，涉及库、Python 环境、Excel 自身等多方面，但现象很明确：app.xml 里的 "Compatible / Openpyxl" 标记在高版本 Python + openpyxl 场景下是个麻烦制造者。

既然知道了问题所在，怎么解决呢？手动改文件肯定不现实，尤其是在需要自动化生成大量报表的场景。

解决方案

下面提供几种可行的方案，从简单尝试到彻底解决。

方案一：尝试更新或固定 `openpyxl` 版本

软件开发中，遇到问题先试试更新或回退库版本，总没错。

原理： openpyxl 的不同版本在生成文件结构、标记处理上可能存在差异。新版本可能修复了旧版的问题，或者旧版本没有引入导致问题的改动。
操作：
1. 尝试最新稳定版：
```
pip install --upgrade openpyxl
```
  运行代码，看看问题是否解决。有时候，最新的版本可能已经注意到了这个问题并进行了修复。
2. 尝试特定旧版本： 如果最新版不行，可以试试回退到 Python 3.7 环境下工作正常的那个版本，或者它之后的一些稳定版本。
  首先，找到你之前能正常工作的 openpyxl 版本（如果在旧环境里 pip freeze 查看）。
  然后安装指定版本，例如：
```
pip install openpyxl==3.0.9
```
  （请将 3.0.9 替换为你测试有效的版本号）
  多尝试几个版本，看哪个版本能在你的高版本 Python 环境下正常工作。
评价： 这是最简单直接的方法，如果能行，省时省力。但不保证一定有效，因为问题可能涉及 Python 版本和 openpyxl 版本的复杂交互。

方案二：程序化修改 `app.xml`

既然手动修改 app.xml 有效，那我们就用代码来自动化这个过程。这需要我们在 openpyxl 保存文件之后，对生成的 .xlsx 文件进行二次处理。

原理： 利用 Python 的 zipfile 模块像处理 ZIP 压缩包一样读写 .xlsx 文件，找到 docProps/app.xml，用 XML 解析库（如 xml.etree.ElementTree）修改其内容，然后重新打包。

操作步骤与代码示例：

import zipfile
import xml.etree.ElementTree as ET
import os
import shutil
from io import BytesIO

def fix_openpyxl_chart_issue(xlsx_filepath):
    """
    处理 openpyxl 在高版本 Python 下生成的图表显示问题。
    通过修改 xlsx 文件内的 app.xml，移除 'Compatible / Openpyxl' 标记。

    :param xlsx_filepath: 需要修复的 xlsx 文件路径
    """
    print(f"开始处理文件: {xlsx_filepath}")
    temp_zip_filepath = xlsx_filepath + ".tmp.zip" # 临时文件

    try:
        # 1. 将原始 xlsx 复制为一个临时的 zip 文件，避免直接操作原文件
        shutil.copyfile(xlsx_filepath, temp_zip_filepath)

        # 用于存储修改后的文件内容
        output_buffer = BytesIO()

        # 2. 打开临时 zip 文件进行读写
        with zipfile.ZipFile(temp_zip_filepath, 'r') as zin:
            with zipfile.ZipFile(output_buffer, 'w', zipfile.ZIP_DEFLATED) as zout:
                # 遍历 zip 包里的所有文件
                for item in zin.infolist():
                    content = zin.read(item.filename)

                    # 3. 找到 app.xml 并修改
                    if item.filename == 'docProps/app.xml':
                        print("找到 docProps/app.xml，进行修改...")
                        # 使用 ElementTree 解析 XML 内容
                        try:
                            tree = ET.fromstring(content)
                            # 查找 Application 标签 (通常在 Properties 命名空间下)
                            # 注意：XML 可能有命名空间，需要正确处理
                            namespaces = {'vt': 'http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes'} # 根据实际XML结构调整
                            # 通用方式查找 Application 标签，不假设命名空间前缀
                            app_tag = None
                            for elem in tree.iter():
                                 # ElementTree 的 tag 属性会包含命名空间 {uri}tagname
                                 if elem.tag.endswith('Application'):
                                      app_tag = elem
                                      break

                            if app_tag is not None and app_tag.text and 'Compatible / Openpyxl' in app_tag.text:
                                 print(f"原始 Application 标签内容: {app_tag.text}")
                                 # 移除 'Compatible / Openpyxl' 部分，保留其他可能的内容 (虽然通常只有这个)
                                 # 更安全的做法是直接设置为空或目标值，如 "Microsoft Excel"
                                 # 这里选择置空文本内容，根据观察，这通常能解决问题
                                 app_tag.text = app_tag.text.replace('Compatible / Openpyxl', '').strip()
                                 # 或者直接设置为 'Microsoft Excel' (需要测试兼容性)
                                 # app_tag.text = "Microsoft Excel"
                                 print(f"修改后 Application 标签内容: {app_tag.text if app_tag.text else '空'}")

                                 # 将修改后的 XML 转换回字节流
                                 # 必须显式指定 XML 声明和编码，与原始文件保持一致
                                 modified_content = ET.tostring(tree, encoding='UTF-8', xml_declaration=True)
                                 content = modified_content # 使用修改后的内容
                            else:
                                 print("Application 标签未找到或内容无需修改。")

                        except ET.ParseError as e:
                            print(f"解析 app.xml 出错: {e}，跳过修改此文件。")
                            # 出错则保留原始 content 不变

                    # 4. 将文件（无论是原始的还是修改过的）写入新的 zip 输出流
                    zout.writestr(item, content)

        # 5. 用修改后的内容覆盖原始文件
        with open(xlsx_filepath, 'wb') as f:
            f.write(output_buffer.getvalue())

        print(f"文件处理完成: {xlsx_filepath}")

    except Exception as e:
        print(f"处理文件 {xlsx_filepath} 时发生错误: {e}")
    finally:
        # 6. 清理临时文件
        if os.path.exists(temp_zip_filepath):
            os.remove(temp_zip_filepath)
            print(f"临时文件已删除: {temp_zip_filepath}")

# --- 使用示例 ---
# 假设你已经用 openpyxl 生成了文件 'report.xlsx'
# workbook.save('report.xlsx')

# 在保存后调用修复函数
# fix_openpyxl_chart_issue('report.xlsx')

# 你的 openpyxl 图表生成代码...
# from openpyxl import Workbook
# from openpyxl.chart import BarChart, Reference
# 
# wb = Workbook()
# ws = wb.active
# 
# data = [
#     ['类别', '系列1', '系列2'],
#     ['A', 10, 30],
#     ['B', 40, 60],
#     ['C', 50, 70],
#     ['D', 20, 10],
# ]
# for row in data:
#     ws.append(row)
# 
# chart = BarChart()
# chart.title = "示例图表"
# chart.style = 10
# 
# values = Reference(ws, min_col=2, min_row=1, max_col=3, max_row=5)
# cats = Reference(ws, min_col=1, min_row=2, max_row=5)
# chart.add_data(values, titles_from_data=True)
# chart.set_categories(cats)
# ws.add_chart(chart, "E5")
# 
# file_path = 'test_chart_py_high.xlsx'
# wb.save(file_path)
# 
# print(f"原始文件已保存: {file_path}")
# 
# # 调用修复函数
# fix_openpyxl_chart_issue(file_path)

代码解释：
- 函数 fix_openpyxl_chart_issue 接收 .xlsx 文件路径作为参数。
- 使用 shutil.copyfile 创建一个临时文件操作，更安全。
- 使用 zipfile 模块以读模式打开临时文件 (zin)，同时以写模式打开一个内存中的 BytesIO 对象 (zout) 用于构建新的 ZIP 包。
- 遍历原 ZIP 包中的每一项 (item)。
- 读取每一项的内容 (content)。
- 判断文件名是否为 docProps/app.xml。如果是，则：
  - 使用 xml.etree.ElementTree.fromstring 解析 XML 内容。
  - 查找 <Application> 标签。这里需要注意 XML 命名空间（namespace），代码中尝试用一种通用方式查找。
  - 如果找到且其文本包含 "Compatible / Openpyxl"，则修改其文本内容（这里是清空或移除该特定字符串）。
  - 使用 ET.tostring 将修改后的 Element 对象转换回带 XML 声明的 UTF-8 字节流。
  - 用修改后的内容替换原始 content。
- 将 content（可能是原始的，也可能是修改过的 app.xml）通过 zout.writestr(item, content) 写入新的 ZIP 结构中。item 参数保留了原始的文件信息（如文件名、压缩方式等）。
- 循环结束后，output_buffer 中就包含了修改后的整个 .xlsx 文件内容。
- 最后，将 output_buffer 中的内容写回原始文件路径，完成覆盖。
- 添加了 try...except...finally 结构来处理潜在错误并确保临时文件被删除。
进阶与安全建议：
- 健壮性： 上面的代码做了基本的错误处理，但在生产环境中，你可能需要更细致的错误处理，比如对 XML 解析失败、文件读写权限问题等进行捕获和记录。
- XML 命名空间： app.xml 的确切结构和命名空间可能随 Office 版本或 openpyxl 版本变化。代码中对命名空间的处理可能需要根据实际 app.xml 文件调整。可以先解压一个文件出来看看 app.xml 的具体内容，尤其是根元素的 xmlns 定义。
- 性能： 对于非常大的 Excel 文件，频繁的解压和压缩可能有效率问题。如果性能是瓶颈，可能需要寻找更底层的库或者不同的策略。
- 备份： 在自动化流程中加入这一步前，务必充分测试，并考虑对原始文件做备份，以防修改过程出错导致文件损坏。
评价： 这是目前看来最可靠且能集成到自动化流程中的方法。虽然代码稍微复杂一点，但一劳永逸地解决了问题，无需关心 openpyxl 或 Python 的具体版本组合。

方案三：检查图表创建代码本身

虽然问题看起来和版本关系很大，但也不能完全排除图表创建代码写法的细微差别导致的可能性。

原理： openpyxl 的 API 在不同版本间可能有微小变化或默认值调整。某些在高版本下不再推荐或行为有变的用法，可能导致图表定义不正确。
操作：
- 仔细对照你使用的 openpyxl 版本的官方文档，检查你的图表创建代码。特别是关于数据系列 (Reference)、类别轴 (set_categories)、图表类型 (BarChart, LineChart 等)、样式 (chart.style)、布局 (chart.layout) 等相关的设置。
- 尝试简化图表创建代码，只保留最基本的数据和设置，看是否能正常显示。如果可以，再逐步添加其他配置，找出是哪个具体设置导致了问题。
评价： 作为辅助排查手段。如果前两种方法都没用，或者你怀疑自己的代码用法比较特殊，可以检查一下。但根据问题，版本依赖性是主要矛盾。