You need to enable JavaScript to run this app. 基于PDFKit与Strapi(Koa)实现GET接口管道输出PDF的流提前关闭问题
优惠活动
大模型
产品
解决方案
定价
更多

基于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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.07 06:06:03