简介：面向Django开发者的实用技术文档，聚焦在项目中导出数据至Excel并实现浏览器下载的常见需求，适合初中级后端工程师快速掌握实现路径。资料包仅含1个PDF文档，大小77KB，内容精炼，便于快速阅读与按需查阅。文档从依赖模块安装写起，详细介绍了使用xlwt创建Excel工作簿、在Django视图里设置HttpResponse与Content-Disposition响应头以生成.xls附件，以及前端通过XMLHttpRequest发送POST请求并用Blob对象触发下载的完整流程。针对大数据量下载场景，还补充了百万级、千万级数据避免MemoryError和nginx超时的优化思路，包括采用StreamingHttpResponse进行流式传输的原理与示例，帮助读者规避常见性能陷阱。已有1498人学习下载，表明该主题在Django社区具有较高需求，对于希望系统掌握Excel导出与下载交互细节的开发者而言，是一份值得参考的系统化资料。
1. 从「导出按钮转圈圈」说起：Django 导出 Excel 到底难在哪
做过 Django 项目实战新手的人，大概率都经历过这个场景：运营在后台点「导出报表」，页面转了十几秒，最后浏览器下载了一个 0KB 的文件，或者干脆报 504。这时候你打开服务器日志，发现视图函数里用 pandas 直接读了全表，内存炸了。这个标题要解决的，就是「在有 Django 的 Web 项目里，把数据库里的数据安全、高效地写成 Excel 文件，并让浏览器正常触发下载」这一整套链路。你需要处理的不只是「python写入excel」这一个动作，还有响应头的设置、大文件的内存控制、中文文件名编码，以及各种会让 Excel 打不开的隐藏坑。本文适合已经会写基础 Django 视图、但没正经做过文件导出的开发者，也适合想从「能用」做到「抗造」的进阶用户。
2. 选型与最小闭环：用 openpyxl 还是 xlwt，以及第一个可下载的 Excel
先说结论：只要是给 Django 2.x 以上项目做导出，我一般直接用 openpyxl，不再碰 xlwt。xlwt 只能写 .xls 老格式，单表行数上限 65535，Unicode 支持也别扭；而 openpyxl 写 .xlsx，行数上限百万级，对现代办公软件兼容也好。另一个常被拿来对比的库是 xlsxwriter，它性能更好、对格式控制更细，但没有 openpyxl 读写的灵活度。如果只是导出数据，xlsxwriter 其实比 openpyxl 更合适。不过考虑到很多人后续要读 Excel 做「excel导入数据库」的逆操作，openpyxl 一个库能同时覆盖读和写，减少依赖，所以我下面的例子默认用 openpyxl，中途会标注 xlsxwriter 的差异。
2.1 建立一个独立 service 模块：别把导出逻辑写进视图
很多人喜欢直接在 views.py 里从查询集开始一路写到 HttpResponse，代码是能跑，但下次想复用或者在 management command 里调用就得复制粘贴。我建议第一步先建一个独立的 service 文件，比如在 app 目录下建services.py，专门放导出逻辑。
# orders/services.py from openpyxl import Workbook def build_orders_workbook(queryset): """ 根据传入的 queryset 生成 Workbook 对象。 不在这里处理响应，只负责把数据填进 Excel。 """ wb = Workbook() ws = wb.active ws.title = "订单列表" # 写表头 headers = ["订单号", "用户", "金额", "状态", "创建时间"] ws.append(headers) # 写数据 for order in queryset.iterator(chunk_size=500): ws.append([ order.order_no, order.user.username if order.user else "", order.amount, order.get_status_display(), order.created_at.strftime("%Y-%m-%d %H:%M:%S"), ]) return wb这里的核心逻辑是：函数接收一个 queryset，通过iterator(chunk_size=500)分块遍历，而不是一次性list(queryset)把全部对象加载进内存。ws.append是按行追加，注意get_status_display()拿到的是 choices 里定义的中文标签而不是存库的英文键，这个习惯很重要，后面避坑章节会展开说。时间字段先格式化成字符串，避免 Excel 显示一堆序列号。
2.2 在视图里组装下载响应：三个响应头的关键设置
有了 Workbook 对象，接下来的事是把它变成浏览器能认领的下载文件。这里有几个新手容易翻车的点：首先，Workbook 不能直接塞进 HttpResponse，必须保存到内存字节流；其次，Content-Type 要用对；最后，Content-Disposition 里的文件名必须是编码后的。
# orders/views.py import io from django.http import HttpResponse from .services import build_orders_workbook def export_orders_view(request): # 实际项目里这里会有 filterset 之类的查询条件拼装 queryset = Order.objects.filter(status="paid").select_related("user") wb = build_orders_workbook(queryset) # 保存到内存字节流 buffer = io.BytesIO() wb.save(buffer) buffer.seek(0) # 组装响应 response = HttpResponse( buffer.getvalue(), content_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" ) # 注意文件名这里要做 urlquote，不然中文名会乱码 filename = "paid_orders_202501.xlsx" response["Content-Disposition"] = f"attachment; filename*=utf-8''{filename}" return response代码里几个关键点：io.BytesIO是必须的，openpyxl 的 save 方法接受文件路径或文件对象，如果传字符串路径就直接写到服务器磁盘了，除非你有持久化需求，否则内存流更干净。content_type必须用 xlsx 的专用 MIME 类型，如果你用text/plain或application/octet-stream，浏览器可能直接把它塞进新标签页而不是触发下载。filename*=utf-8''是 RFC 5987 的标准写法，针对非 ASCII 文件名。如果文件名里有空格，建议把空格替换成下划线，省得某些浏览器和代理服务器发疯。
3. 参数化查询与字段映射：让导出的数据「跟页面看到的一样」
很多 Django 项目里，列表页是有筛选条件的，比如时间范围、状态、销售渠道。导出不能把全表数据丢给用户，必须复用前端的筛选逻辑。这里最常见的坑是有人直接复制粘贴查询代码，结果前端加了筛选，导出没跟上。正解是把筛选参数抽象成公共方法，视图和导出都调用同一套。
3.1 用 Django FilterSet 复用筛选条件并做导出参数校验
假设项目里已经装了 django-filter，列表页用的 FilterSet 定义了一堆筛选字段。导出接口可以复用同一个 FilterSet，但参数来源变成了 request.GET，且需要额外处理分页器不能用在导出上的问题。
# orders/filters.py import django_filters as filters from .models import Order class OrderFilter(filters.FilterSet): class Meta: model = Order fields = ["status", "channel"] paid_at_after = filters.DateTimeFilter(field_name="paid_at", lookup_expr="gte") paid_at_before = filters.DateTimeFilter(field_name="paid_at", lookup_expr="lt") # orders/services.py def build_orders_workbook_from_filters(filterset): """接收一个已经绑定数据的 FilterSet，返回 Workbook""" wb = Workbook() ws = wb.active ws.title = "导出结果" headers = ["订单号", "渠道", "支付时间"] ws.append(headers) # filterset.qs 是已经筛选好的 QuerySet for order in filterset.qs.select_related("user").iterator(chunk_size=500): ws.append([order.order_no, order.get_channel_display(), order.paid_at]) return wb注意ws.append([order.order_no, order.get_channel_display(), order.paid_at])这条，我把时间对象直接塞进 append 了。openpyxl 支持写入 datetime 对象，会在 Excel 里显示为原生日期时间，配合列宽调整就是可读的。但如果你导出的时间字段带时区且要发给海外同事，建议统一转成 UTC 或指定时区，否则各人看到的数值可能对不上账。
参数校验这里是隐式的：FilterSet 在绑定 request.GET 时已经处理了非法值，比如paid_at_after=abc会被自动忽略并标记错误。但你说要导出时，最好主动检查filterset.is_valid()，无效就返回 400 或者提示信息，避免用户默默地拿到一份没有筛选的完整表。
3.2 处理好关联字段：select_related、prefetch_related 与外键空值
导出数据时最常见的性能杀手是 N+1 查询。你写order.user.username，如果没做 select_related，Django 会对每一行额外查一次用户表。几千行数据时感觉不明显，几万行时就是灾难。上面代码里的select_related("user")就是为此存在的。
# 性能对比演示代码（作为参考写法，可放在具体视图或 service 里） from django.db.models import Prefetch # 一对多场景，比如导出每个订单的所有商品行 def build_order_items_workbook(queryset): wb = Workbook() ws = wb.active ws.append(["订单号", "商品名", "数量", "单价"]) # 用 prefetch_related 一次拉取全部商品 qs = queryset.prefetch_related( Prefetch("items", queryset=OrderItem.objects.all().only("name", "quantity", "price")) ) for order in qs.iterator(chunk_size=200): for item in order.items.all(): ws.append([order.order_no, item.name, item.quantity, item.price]) return wbprefetch_related传Prefetch对象并配合only()，相当于告诉数据库只要这三列，别把整行大字段都传过来。对于一对多展开，这种写法比在循环里反复order.items.all()减少了几百倍查询。还有个细节是外键空值：如果order.user可能是 None，在导出模板里必须写order.user.username if order.user else ""，否则空值直接触发 AttributeError 让导出任务中断。这个在build_orders_workbook里已经写过了，但实际项目里可能还有多个外键，每个都判断会显得啰嗦，可以给 User 模型加一个display_nameproperty 统一处理，模板里永远只调order.user.display_name。
4. 从「能用」到「抗造」：超大查询集的流式导出与内存边界
前面的代码已经能支撑日常导出了，但真正让 Django 项目实战产生质变的，是处理超大查询集。比如运营想要导出过去一年的所有订单，数据五十万行，openpyxl 的ws.append也会把全部单元格放在内存里。实测经验是：openpyxl 内存占用是数据本身的 5 到 10 倍，五十万行能把你 8G 内存的开发机直接拖死。这里需要两条路并行：用生成器分批写，以及改用 xlsxwriter 的流式写入。
4.1 降级方案：限制导出总量与异步化处理
先给一个哪怕是新手也能直接落地的保守方案，避免生产事故。
# orders/views.py from django.core.cache import cache MAX_EXPORT_ROWS = 100000 def export_orders_safe(request): filterset = OrderFilter(request.GET, queryset=Order.objects.all()) total = filterset.qs.count() if total > MAX_EXPORT_ROWS: return HttpResponse("导出行数超过 %s，请缩小时间范围" % MAX_EXPORT_ROWS, status=413) # 生成导出任务 ID，走后台队列，前端轮询下载 task_id = uuid.uuid4().hex cache.set(f"export_task_{task_id}", {"status": "processing", "progress": 0}, 60 * 60) # 真正干活时可以用 celery 或 django-q，这里略写 # generate_export_task.delay(filterset.qs, task_id) return HttpResponse(f"任务已创建，task_id={task_id}")这里count()在超大表上也可能慢，但对百万级订单表来说也就几百毫秒到一两秒，可以接受。超过限制直接 413 拒绝，比试图硬扛要稳妥。后台异步化是成熟项目的必经之路，但如果你只有一台小服务器、不想引入 celery，可以把导出任务放在一个管理命令里跑，输出到本地文件，再由 Nginx 直接提供静态下载。这个方案最简单，也不容易出内存事故。
4.2 内存不足时的最后手段：用 xlsxwriter 的 constant_memory 模式
如果业务方坚持要一次导出全量数据，且你手里是单机 Django，没有队列服务，那最好的选择就是 xlsxwriter 的constant_memory模式。
# orders/services_wsx.py import xlsxwriter def build_orders_xlsxwriter(queryset, file_path): workbook = xlsxwriter.Workbook(file_path, {'constant_memory': True}) worksheet = workbook.add_worksheet('订单导出') headers = ['订单号', '用户', '金额'] for col, h in enumerate(headers): worksheet.write(0, col, h) row = 1 for order in queryset.iterator(chunk_size=1000): worksheet.write(row, 0, order.order_no) worksheet.write(row, 1, order.user.username if order.user else '') worksheet.write(row, 2, order.amount) row += 1 workbook.close() # 必须 close，否则文件不完整constant_memory: True会强制 xlsxwriter 在内存中只保留当前一行和索引信息，到达写入上限时把已完成的行排到磁盘上。代价是牺牲了一些功能：比如不能先写数据再回头调整列宽、不能用公式引用前面单元格。它写的是磁盘文件而不是 BytesIO，所以内存压力被转移到了磁盘上。这里的file_path必须是服务器可写路径，通常放在MEDIA_ROOT/export/下，任务完成后用 Django 的信号器或者简单地在响应里直接 FileResponse 给用户。注意workbook.close()必须在返回文件之前调用，否则文件没有终止标记，Excel 会提示文件损坏。
5. 下载功能的避坑指南：前端拿不到文件、Excel 打不开、中文名乱码
这一章专门收集我在真实项目里见过的血泪经验。每一条都对应一个实际生产的坑，按「现象 → 原因 → 解决」来写，少走弯路。
5.1 浏览器把接口返回的 JSON 当文件下载，文件名是 random
现象：前端用 axios 请求导出接口，responseType 没设置，结果下载下来的是一个 JSON 文件，里面是错误信息或一个 Blob 对象的字符串。原因：导出接口如果抛了异常，Django 会返回 500 页面或 JSON 错误，而前端代码仍然像成功一样调URL.createObjectURL。解决：前端请求时显式声明responseType: 'blob'并检查响应的content-type，如果是 JSON 说明后端报错了。
// 前端下载示意 axios.get('/api/export/orders/', { params: params, responseType: 'blob' }) .then(res => { if (res.data.type === 'application/json') { console.error('后端返回了错误，不是 Excel'); return; } const url = window.URL.createObjectURL(new Blob([res.data])); const link = document.createElement('a'); link.href = url; link.setAttribute('download', 'orders.xlsx'); document.body.appendChild(link); link.click(); });5.2 下载下来的文件用 Excel/WPS 打开是乱码
现象：文件能下载，但打开后所有中文变成了「锟斤拷」或者问号。原因：Excel 对 UTF-8 的 CSV 支持不佳，但.xlsx应该是不会乱码的。如果你导出的是 CSV（有些项目图省事用text/csv），那就需要在内容前面加 BOM 头。解决：如果是 CSV，把响应的内容改为b'\xef\xbb\xbf' + csv_content；如果是 xlsx 乱码，一般是 openpyxl 写入时用了不支持的字符集，检查一下有没有 emoji 或特殊符号，openpyxl 默认不支持某些字体符号，可以改用utils.escape处理。从我角度说，干脆别用 CSV 导出中文，一律 xlsx，省掉一半问题。
5.3 下载的文件提示「文件已损坏，无法打开」
现象：浏览器下载正常，文件名也对，但双击提示文件损坏。原因：绝大多数情况是因为数据量太大，openpyxl 保存时把内存写爆，产生了截断文件；或者response = HttpResponse(content_type=...)之后又往 response 里追加了日志、print 输出。第二种情况在 Django 开发服务器里太常见了，你调试时顺手print(queryset)，这些字符会被捕获进响应体，把 xlsx 的二进制结构破坏了。解决：不要在生成响应的视图函数里使用print()或调试日志；导出函数用单独的 service 文件并在 where 条件确认没有流式输出到 stdout。如果确认没这个问题，就按 4.2 的 constant_memory 方案处理大数据量。
5.4 文件名是中文时，Chrome 正常但 Safari 下载乱码
现象：Content-Disposition 里写了中文名，Chrome / Edge 正常，Safari 下载出来的文件名是%E6%88%91.xlsx这种百分号编码。原因：早期 Safari 对 RFC 5987 的filename*支持不完整。解决：保守做法是同时给filename和filename*，前者用 ASCII 文件名，后者用 UTF-8 编码。
filename = "订单.xlsx" # ASCII 兜底名 ascii_name = "orders.xlsx" response["Content-Disposition"] = ( f"attachment; filename=\"{ascii_name}\"; filename*=UTF-8''{urlquote(filename)}" )这条经验是一次又一次翻车换来的，建议直接抄进你的工具函数里。
5.5 导出接口超时被 Nginx / Gunicorn 掐断
现象：数据量大时，请求执行到一半被网关掐断，前端收到 504，服务器日志里有 worker timeout。原因：默认 uwsgi/Gunicorn 的 worker 超时通常 30 到 60 秒，十万行数据的序列化和 Excel 写入早就超了。解决：如果是同步导出，把 Gunicorn 的这个超时调大不治本，因为会阻塞所有请求。正确做法是异步任务 + 前端轮询文件生成状态。这里推荐一个不引额外依赖的方案：在 Django 里起一个 daemon 线程执行导出，状态写进 cache 表，另一个接口查询状态，生成完成后给前端返回文件 URL，前端带着 token 去下载。
import threading def export_async(request): task_id = str(uuid.uuid4()) fs = OrderFilter(request.GET, queryset=Order.objects.all()) # 把查询条件序列化到任务里 cache.set(f"export_task_{task_id}", {"status": "pending"}, 60 * 60) def _run(): wb = build_orders_workbook(fs.qs) buffer = io.BytesIO() wb.save(buffer) # 保存到磁盘或网盘 cache.set(f"export_task_{task_id}", {"status": "done", "size": buffer.tell()}, 60 * 60) threading.Thread(target=_run).start() return JsonResponse({"task_id": task_id})注意 daemon 线程在进程重启后会丢，生产上只是权宜之计，引入 celery 才是正解。但在小项目里，这个方案能撑住日均几十次的导出任务。
6. 进阶一点：用 pandas 直接输出 Excel 与数据透视表的取舍
后半部分聊聊当你的导出需求不再是一张单纯的二维表，而是带统计、带分页签、甚至带图表的报表时怎么处理。我个人经验是：报表越复杂，越不要硬用 openpyxl 从零画格子，直接用 pandas 的to_excel方法搭骨架，再用 xlsxwriter 调整格式，两手配合效率最高。
# orders/reports/pandas_export.py import pandas as pd def export_sales_summary(queryset): df = pd.DataFrame(list(queryset.values("channel", "amount", "paid_at"))) df["paid_month"] = df["paid_at"].dt.to_period("M").astype(str) pivot = pd.pivot_table(df, index="paid_month", columns="channel", values="amount", aggfunc="sum", fill_value=0) with pd.ExcelWriter("sales_summary.xlsx", engine="xlsxwriter") as writer: pivot.to_excel(writer, sheet_name="月度汇总") worksheet = writer.sheets["月度汇总"] worksheet.set_column("A:E", 18)这里pd.ExcelWriter底层就是 xlsxwriter，支持set_column调整列宽。pivot_table一步生成多 Sheet 的汇总表，比手写循环判断高效得多。要注意的是 pandas 在导出时会把整份 DataFrame 一次性加载进内存，所以这种情况不适合超大明细表，只适合已经聚合好的结果。
最后一个值得投资的习惯：给导出模块写一个小的单元测试，用 DjangoTestCase构造几条假数据，调用build_orders_workbook后直接openpyxl.load_workbook反向读取，断言单元格内容。这个测试的成本极低，但能帮你挡住大部分因字段名改动引起的导出报表翻车。在持续交付里，导出功能是很容易被忽略的角落，但只要它坏一次，运营和财务就会同时找上门。希望这条路径和这些踩过的坑对你有用。
本文还有配套的精品资源，点击获取
