本文详解如何正确实现 Flask 生成 .docx 文件并通过 Vue.js 客户端触发下载，避免文件损坏问题，核心在于后端正确设置响应头、前端以 Blob 方式处理二进制流而非 JSON 解析。
本文详解如何正确实现 flask 生成 `.docx` 文件并通过 vue.js 客户端触发下载，避免文件损坏问题，核心在于后端正确设置响应头、前端以 blob 方式处理二进制流而非 json 解析。
在 Web 应用中，前端（Vue.js）直接生成复杂 DOCX 文件容易出错，因此推荐将文档生成逻辑交由后端（Flask）完成——使用 python-docx 和 html-to-docx 库可靠构建 Word 文档，并通过 HTTP 流式响应返回二进制内容。但若前端未正确处理响应体（例如误将其当作 JSON 解析），就会导致文件损坏。
✅ 正确的 Flask 后端实现（已基本正确，仅需微调）
你的 Flask 路由逻辑整体合理，但建议补充关键响应头并显式关闭缓存，确保浏览器不缓存或错误解析响应：
from flask import send_file, make_response
from io import BytesIO
from docx import Document
from html_to_docx import HtmlToDocx
def download_docx():
try:
data = request.get_json()
html_content = data.get('docxData', '')
document = Document()
parser = HtmlToDocx()
parser.add_html_to_document(html_content, document)
docx_buffer = BytesIO()
document.save(docx_buffer)
docx_buffer.seek(0)
response = make_response(send_file(
docx_buffer,
mimetype='application/vnd.openxmlformats-officedocument.wordprocessingml.document',
as_attachment=True,
download_name='test.docx', # Flask 2.0+ 推荐用 download_name；旧版用 attachment_filename
cache_timeout=0
))
# 强制禁用缓存 & 防止 MIME 类型嗅探
response.headers['Cache-Control'] = 'no-cache, no-store, must-revalidate'
response.headers['Pragma'] = 'no-cache'
response.headers['Expires'] = '0'
response.headers['X-Content-Type-Options'] = 'nosniff'
return response
except Exception as e:
print(f"DOCX generation error: {e}")
return {'error': 'Failed to generate document'}, 500
⚠️ 注意：send_file 在较新 Flask 版本中推荐使用 download_name 替代 attachment_filename，并确保 BytesIO 对象未被提前关闭。
✅ 正确的 Vue.js 前端下载逻辑（关键修正点）
你原始代码的问题在于：
❌ response.data 默认被 Axios 当作 JSON 解析（因默认 responseType: 'json'），导致二进制 DOCX 数据被错误转码为字符串，文件必然损坏。
✅ 正确做法是显式指定 responseType: 'blob'，并调用 response.blob() 获取原始二进制流。
以下是推荐的完整 Vue 方法（兼容 Vue 2/3 + Axios）：
import axios from 'axios'
export function downloadDocx(token, data) {
const headers = { ...authHeader(token), 'Content-Type': 'application/json' }
return axios.post(`${API_URL}/download/docx`, data, {
headers,
responseType: 'blob', // ? 关键！必须设置为 'blob'
})
}
// 组件内调用
downloadDocx() {
const data = { docxData: this.fullHtml }
this.$store.dispatch('downloadDocx', data)
.then(response => {
if (response.status === 200 && response.data instanceof Blob) {
const blob = response.data
const url = window.URL.createObjectURL(blob)
const link = document.createElement('a')
link.href = url
link.download = 'test.docx'
link.style.display = 'none'
document.body.appendChild(link)
link.click()
document.body.removeChild(link)
window.URL.revokeObjectURL(url) // 清理内存
} else {
throw new Error('Invalid response')
}
})
.catch(err => {
console.error('Download failed:', err)
alert('无法下载文档，请检查网络或重试')
})
}
✅ 进阶推荐：使用 FileSaver.js 简化流程
为提升兼容性与可维护性，建议引入 FileSaver.js（轻量、支持 IE10+）：
npm install file-saver
import { saveAs } from 'file-saver'
// 替换下载逻辑：
.then(response => {
const blob = new Blob([response.data], {
type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
})
saveAs(blob, 'test.docx') // 自动触发下载，无需手动创建 <a> 标签
})</a>
? 总结与注意事项
- 永远设置 responseType: 'blob'：这是防止 DOCX 损坏的首要前提；
- 避免对二进制响应调用 .json() 或直接访问 .data 字符串；
- Flask 中确保 mimetype 和 download_name 准确无误，并添加安全响应头；
- 测试时用 curl -v -X POST ... 直接验证接口是否返回原始二进制流（HTTP 状态码 200 + Content-Type: application/vnd.openxml...）；
- 如需支持大文件，考虑添加加载状态与错误重试机制。
遵循以上方案，即可稳定、可靠地从 Flask 后端生成并下载结构完整的 .docx 文件。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
