基于PDFKit与Strapi(Koa)实现GET接口管道输出PDF的流提前关闭问题
Strapi 接口返回PDF的正确实现方案
根因说明
原实现的问题并非doc.end()执行时机过早,核心矛盾来自Strapi基于Koa的响应机制:
- Koa框架默认会在控制器同步代码执行结束后,自动接管响应流程,对设置的
ctx.body做序列化、头部校验、流关闭操作 - 原代码直接将PDF流管道绑定到原生
ctx.res时,没有禁用Koa的默认响应接管逻辑,会导致Koa在控制器同步代码跑完时,提前切断底层响应连接,使得PDFKit生成的后续流式内容无法完整传输,最终输出的PDF文件因chunk缺失无法被正常解析 - 缺少必要的响应头配置,部分客户端会无法正确识别返回的PDF格式内容
修正后的控制器代码
const PDFDocument = require("pdfkit"); module.exports = { async printOne(ctx) { // 初始化PDF实例,配置文档元信息 const doc = new PDFDocument({ info: { Title: "Test Document", Author: "Devon Govett" } }); // 配置响应头 ctx.response.set({ "Content-Type": "application/pdf", "Content-Disposition": "inline; filename=test.pdf" }); // 关键:禁用Koa默认响应处理逻辑,告知框架当前响应已被手动接管 ctx.respond = false; // 建立PDF生成流到HTTP响应管道 doc.pipe(ctx.res); // 写入PDF正文内容 doc.text("Hello world!"); // 监听PDF流生成完成事件,所有内容写入管道后再关闭底层连接 doc.on("end", () => { ctx.res.end(); }); // 触发PDF文档生成流程 doc.end(); }, };
实现要点
- 必须设置
ctx.respond = false,这是避免Koa提前截断流的核心配置 - 不要依赖同步代码顺序判断PDF是否生成完成,通过监听PDF实例的
end事件确认所有流式内容推送完毕后,再关闭底层HTTP连接 - 若需要让客户端触发下载弹窗,只需将
Content-Disposition的值调整为attachment; filename=test.pdf - 无需额外增加延时逻辑,PDFKit本身为流式生成模式,管道建立后内容会逐块推送到客户端,不会造成请求阻塞
- 建议给PDF实例增加
error事件监听,生成流异常时直接返回500状态码,避免连接长期挂起
内容的提问来源于stack exchange,提问作者antonitor
相关产品推荐
相关产品推荐

