如何在heroku stack-20安装imagemagic buildpack实现PDF转图片

这类适配问题的核心原因有两点：一是大部分PDF转图片的npm包都是系统命令的薄封装，缺少对应底层依赖就无法运行；二是Heroku默认运行环境既没有预装PDF解析必需的Ghostscript，ImageMagick默认安全策略也会直接拦截PDF格式读写，直接照搬本地配置必然失效。

方案1：最小改动适配现有ImageMagick调用逻辑 #

这个方案不需要改动已写好的命令调用逻辑，只需要补全环境配置即可：

• 第一步：添加apt构建包安装系统依赖
  不要用来源不明的第三方ImageMagick buildpack，直接用官方维护的apt插件安装完整依赖：
  1. 执行命令添加apt buildpack：

     heroku buildpacks:add --index 1 heroku-community/apt
     

  2. 在项目根目录新建Aptfile，写入需要安装的系统包：

     ghostscript
     imagemagick
     

• 第二步：覆盖ImageMagick默认安全策略
  Heroku软件源里的ImageMagick默认禁用PDF格式读写权限，需要自定义策略文件绕过限制。在项目根目录新建policy.xml：

  <policymap>
    <policy domain="coder" rights="read|write" pattern="PDF" />
    <policy domain="resource" name="memory" value="256MiB"/>
    <policy domain="resource" name="disk" value="1GiB"/>
  </policymap>
  

• 第三步：修正现有调用代码
  补全环境变量配置，对文件路径做shell转义避免特殊字符报错，临时目录指定到Heroku可写的/tmp路径：

  const { exec } = require('child_process');
  const path = require('path');
  
  // 转义shell特殊字符，避免空格、特殊符号导致命令失败，同时防范命令注入
  const escapeShell = (arg) => `"${arg.replace(/(["\s'$`\\])/g,'\\$1')}"`;
  const pdfFullPath = path.join(uploadPath, filename.pdf);
  const outputFullPath = path.join(uploadPath, 'output.jpg');
  const policyFullPath = path.join(__dirname, 'policy.xml');
  
  exec(
    `convert -define registry:temporary-path=/tmp -policy ${escapeShell(policyFullPath)} ${escapeShell(pdfFullPath)} -density 300 -quality 100 ${escapeShell(outputFullPath)}`,
    {
      cwd: uploadPath,
      env: {
        ...process.env,
        PATH: `/app/.apt/usr/bin:${process.env.PATH}`
      }
    },
    (error) => {
      if (error) return reject(error);
      // 后续业务逻辑
    }
  );
  

  完成配置后重新部署即可正常运行。

方案2：零系统依赖纯JS实现（稳定性更高） #

如果不想折腾系统级依赖，可以直接用纯npm包实现转换，不需要额外配置buildpack，Heroku默认Node.js环境就能直接跑：

• 安装依赖：

  npm install pdfjs-dist canvas
  

• 核心转换代码：

  const pdfjsLib = require('pdfjs-dist/legacy/build/pdf.js');
  const { createCanvas } = require('canvas');
  const fs = require('fs/promises');
  
  async function convertPdfToJpg(pdfPath, outputPath, dpi = 300) {
    const scale = dpi / 72; // PDF默认基准分辨率为72DPI，按比例缩放对应目标DPI
    const pdfDoc = await pdfjsLib.getDocument(pdfPath).promise;
    // 示例取第一页转换，多页场景循环遍历1到pdfDoc.numPages即可
    const page = await pdfDoc.getPage(1);
    const viewport = page.getViewport({ scale });
    const canvas = createCanvas(viewport.width, viewport.height);
    const renderContext = {
      canvasContext: canvas.getContext('2d'),
      viewport: viewport
    };
    await page.render(renderContext).promise;
    const jpgBuffer = canvas.toBuffer('image/jpeg', { quality: 1 });
    await fs.writeFile(outputPath, jpgBuffer);
  }
  

  这个方案没有任何外部命令依赖，不会出现环境适配问题，长期维护成本更低。

避坑提示 #

• ImageMagick本身没有PDF解析能力，所有不安装Ghostscript的ImageMagick配置都不可能正常处理PDF文件
• Heroku本地文件系统是临时存储，服务重启后文件会被清空，生成的图片如果需要长期保存，要同步到对象存储服务
• 所有拼接shell命令的场景必须对参数做转义，否则会存在命令注入风险，也会导致带空格、特殊字符的文件名处理失败

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