Python3 CGI下OpenPYXL生成内存XLSX文件浏览器下载损坏问题

问题根因 #

文件损坏的核心原因有三点：

• Python 3 的print()函数是面向文本输出设计的，默认走标准输出的文本模式通道，会自动对传入内容做编码转换、追加换行符。直接传入BytesIO生成的二进制字节对象时，print()会先把字节对象转成它的字符串表示形式（也就是你看到的带b'PK...'前缀的内容）再输出，原始二进制结构已经被完全破坏。
• XLSX本质是ZIP格式的二进制压缩包，不属于任何文本编码格式，任何尝试对其做decode()转成文本的操作都会损坏字节结构，最终生成无法被Excel、解压工具识别的损坏文件。
• 原代码中HTTP头的参数等号两侧加了多余空格，部分浏览器会出现文件名解析异常的问题。

修复步骤 #

1. 调整HTTP响应头格式，使用XLSX专属的MIME类型提升兼容性，去掉参数两侧多余空格，确保头和响应体之间用空行正确分隔。
2. 放弃用print()输出二进制文件内容，直接调用标准输出的二进制缓冲接口sys.stdout.buffer.write()，将内存中生成的原始XLSX字节原封不动输出给浏览器，全程不要做任何编码转换。
3. 输出完成后刷新缓冲，避免内容被截断。

可直接运行的修正代码 #

#!/usr/bin/env python
import sys
import io
import openpyxl

# 输出HTTP响应头
print("Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
print("Content-Disposition: attachment; filename=test.xlsx")
# 输出空行分隔响应头和响应体
print()

# 生成Excel文件内容
wb = openpyxl.Workbook()
ws = wb.active
ws['A1'] = "hello"
ws['A2'] = "there!"

# 将Excel写入内存字节流
output = io.BytesIO()
wb.save(output)

# 直接写入原始二进制字节到标准输出
sys.stdout.buffer.write(output.getvalue())
sys.stdout.buffer.flush()

注意事项 #

• 不要对生成的XLSX二进制内容做任何decode()/encode()文本转码操作，二进制文件不需要经过文本编码层处理。
• 不要混用文本输出和二进制输出接口，所有HTTP头用文本模式的print()输出即可，头输出完成后所有文件内容都走二进制缓冲接口输出。
• 如果使用的CGI环境有额外的输出缓冲配置，记得在输出完成后做flush操作，避免末尾内容丢失。

内容的提问来源于stack exchange，提问作者Patrick Rynhart