Como mesclar arquivos PDF em um único PDF usando Node.js

Como faço para mesclar vários arquivos PDF em Node.js?

PdfDocument.merge() aceita um array de objetos PdfDocument e retorna um novo documento contendo todas as páginas na ordem em que os documentos de origem aparecem no array. A operação não é destrutiva; os objetos de arquivo originais não são modificados.

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-pdfs.js
const IronPdf = require('ironpdf');

async function mergePdfs(outputFilePath, inputFiles) {
  // Load all source documents in parallel
  const pdfDocs = await Promise.all(
    inputFiles.map(file => IronPdf.PdfDocument.fromFile(file))
  );

  // Combine into one document, preserving page order
  const mergedPdf = await IronPdf.PdfDocument.merge(pdfDocs);

  // Write the result to disk
  await mergedPdf.toFile(outputFilePath);
  console.log(`Merged PDF saved to ${outputFilePath}`);
}

(async () => {
  const inputFiles = ['report-jan.pdf', 'report-feb.pdf', 'report-mar.pdf'];
  await mergePdfs('quarterly-report.pdf', inputFiles);
})();

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-pdfs.js
const IronPdf = require('ironpdf');

async function mergePdfs(outputFilePath, inputFiles) {
  // Load all source documents in parallel
  const pdfDocs = await Promise.all(
    inputFiles.map(file => IronPdf.PdfDocument.fromFile(file))
  );

  // Combine into one document, preserving page order
  const mergedPdf = await IronPdf.PdfDocument.merge(pdfDocs);

  // Write the result to disk
  await mergedPdf.toFile(outputFilePath);
  console.log(`Merged PDF saved to ${outputFilePath}`);
}

(async () => {
  const inputFiles = ['report-jan.pdf', 'report-feb.pdf', 'report-mar.pdf'];
  await mergePdfs('quarterly-report.pdf', inputFiles);
})();

Promise.all() carrega os arquivos de origem em paralelo, em vez de um de cada vez, o que é importante ao processar coleções maiores. A chamada merge() concatena os documentos na ordem do array, portanto, coloque os arquivos no array na sequência em que você deseja que eles apareçam na saída.

Como faço para mesclar páginas específicas de cada PDF?

Nem sempre o objetivo é copiar todas as páginas de todos os documentos de origem. Para mesclar intervalos de páginas seletivas de cada arquivo de entrada, extraia as páginas desejadas antes de passar os documentos para merge().

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-specific-pages.js
const IronPdf = require('ironpdf');

// Each entry specifies a file and the range of pages to include (zero-indexed)
const pageRanges = [
  { file: 'contract.pdf',  startPage: 0, endPage: 2 },
  { file: 'appendix.pdf',  startPage: 0, endPage: 0 },
  { file: 'signature.pdf', startPage: 0, endPage: 0 },
];

async function mergeSpecificPages(outputFile, ranges) {
  const pdfsToMerge = [];

  for (const range of ranges) {
    const pdf = await IronPdf.PdfDocument.fromFile(range.file);
    // extractPages returns a new PdfDocument with only the specified page range
    const pages = pdf.extractPages(range.startPage, range.endPage);
    pdfsToMerge.push(pages);
  }

  const merged = await IronPdf.PdfDocument.merge(pdfsToMerge);
  await merged.toFile(outputFile);
}

mergeSpecificPages('assembled-contract.pdf', pageRanges);

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-specific-pages.js
const IronPdf = require('ironpdf');

// Each entry specifies a file and the range of pages to include (zero-indexed)
const pageRanges = [
  { file: 'contract.pdf',  startPage: 0, endPage: 2 },
  { file: 'appendix.pdf',  startPage: 0, endPage: 0 },
  { file: 'signature.pdf', startPage: 0, endPage: 0 },
];

async function mergeSpecificPages(outputFile, ranges) {
  const pdfsToMerge = [];

  for (const range of ranges) {
    const pdf = await IronPdf.PdfDocument.fromFile(range.file);
    // extractPages returns a new PdfDocument with only the specified page range
    const pages = pdf.extractPages(range.startPage, range.endPage);
    pdfsToMerge.push(pages);
  }

  const merged = await IronPdf.PdfDocument.merge(pdfsToMerge);
  await merged.toFile(outputFile);
}

mergeSpecificPages('assembled-contract.pdf', pageRanges);

extractPages(startPage, endPage) aceita índices de página baseados em zero. Passar 0, 0 extrai apenas a primeira página, enquanto 0, 2 extrai as três primeiras páginas. O loop constrói um array de documentos de intervalo de página na ordem em que aparecem em ranges, então merge() os concatena na saída final.

Este padrão é útil ao montar contratos a partir de uma página de assinatura, um apêndice e uma folha de rosto armazenados em arquivos separados. Você pode coletar exatamente as páginas que importam de cada fonte sem duplicar arquivos no disco.

Minha biblioteca favorita desse tipo é o IronPDF. Ele permite a manipulação rápida e eficiente de arquivos PDF. Além disso, possui muitos recursos valiosos, como a exportação para o formato PDF/A e a assinatura digital de documentos PDF.

Milan Jovanovic

Microsoft MVP

Veja o estudo de caso

Com o IronOCR, podemos economizar US$ 40.000 por ano em processamento manual, ao mesmo tempo que aumentamos a produtividade e liberamos recursos para tarefas de alto impacto. Eu o recomendo fortemente.

Brent Matzelle

Diretor de Tecnologia, OPYN

Veja o estudo de caso

O IronSuite desempenha um papel crucial nas nossas operações. Estas são ferramentas que aumentam a eficiência no negócio, incluindo a criação de plantas baixas e melhoria na gestão de inventário.

David Jones

Engenheiro(a) de Software Líder, Agorus Build

Veja o estudo de caso

Como adiciono cabeçalhos e rodapés a um PDF mesclado?

Após a fusão, chame addHtmlHeader() e addHtmlFooter() no documento resultante para aplicar cabeçalhos e rodapés consistentes em todas as páginas. Esses métodos aceitam uma string HTML e um objeto de opções.

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-with-headers-footers.js
const IronPdf = require('ironpdf');

async function mergeWithHeadersFooters(inputFiles, outputFile) {
  const docs = await Promise.all(
    inputFiles.map(f => IronPdf.PdfDocument.fromFile(f))
  );
  const mergedPdf = await IronPdf.PdfDocument.merge(docs);

  // Apply a styled header to every page
  await mergedPdf.addHtmlHeader('<h3 style="color:#333;">Quarterly Report</h3>', {
    height: 25,
    drawDividerLine: true,
  });

  // Apply a page-numbering footer
  await mergedPdf.addHtmlFooter('<p style="font-size:10px;">Page {page} of {total-pages}</p>', {
    height: 20,
    drawDividerLine: true,
  });

  await mergedPdf.toFile(outputFile);
}

mergeWithHeadersFooters(['q1.pdf', 'q2.pdf', 'q3.pdf'], 'annual-report.pdf');

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-with-headers-footers.js
const IronPdf = require('ironpdf');

async function mergeWithHeadersFooters(inputFiles, outputFile) {
  const docs = await Promise.all(
    inputFiles.map(f => IronPdf.PdfDocument.fromFile(f))
  );
  const mergedPdf = await IronPdf.PdfDocument.merge(docs);

  // Apply a styled header to every page
  await mergedPdf.addHtmlHeader('<h3 style="color:#333;">Quarterly Report</h3>', {
    height: 25,
    drawDividerLine: true,
  });

  // Apply a page-numbering footer
  await mergedPdf.addHtmlFooter('<p style="font-size:10px;">Page {page} of {total-pages}</p>', {
    height: 20,
    drawDividerLine: true,
  });

  await mergedPdf.toFile(outputFile);
}

mergeWithHeadersFooters(['q1.pdf', 'q2.pdf', 'q3.pdf'], 'annual-report.pdf');

Os espaços reservados {page} e {total-pages} são resolvidos no momento da renderização contra a contagem de páginas do documento mesclado. Use drawDividerLine: true para separar visualmente o cabeçalho ou rodapé do conteúdo da página.

Aplicar cabeçalhos e rodapés após a mesclagem significa que cada página no documento combinado recebe o mesmo tratamento, independentemente de qual arquivo fonte veio. Para opções completas de configuração de cabeçalho e rodapé, veja os exemplos de cabeçalhos e rodapés HTML.

Como protejo um PDF mesclado com senha?

Aplique proteção por senha e restrições de permissão após a fusão, chamando saveAs() com um objeto de opções de segurança. Isso impede o acesso não autorizado ao documento combinado.

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-with-security.js
const IronPdf = require('ironpdf');

async function mergeWithSecurity(inputFiles, outputFile) {
  const docs = await Promise.all(
    inputFiles.map(f => IronPdf.PdfDocument.fromFile(f))
  );
  const mergedPdf = await IronPdf.PdfDocument.merge(docs);

  // Restrict the merged document to print-only access
  await mergedPdf.saveAs(outputFile, {
    userPassword: 'viewerpass',
    ownerPassword: 'adminpass',
    allowUserAnnotations: false,
    allowUserCopyPasteContent: false,
    allowUserFormData: false,
    allowUserPrinting: true,
  });
}

mergeWithSecurity(['invoice-1.pdf', 'invoice-2.pdf'], 'secured-invoices.pdf');

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-with-security.js
const IronPdf = require('ironpdf');

async function mergeWithSecurity(inputFiles, outputFile) {
  const docs = await Promise.all(
    inputFiles.map(f => IronPdf.PdfDocument.fromFile(f))
  );
  const mergedPdf = await IronPdf.PdfDocument.merge(docs);

  // Restrict the merged document to print-only access
  await mergedPdf.saveAs(outputFile, {
    userPassword: 'viewerpass',
    ownerPassword: 'adminpass',
    allowUserAnnotations: false,
    allowUserCopyPasteContent: false,
    allowUserFormData: false,
    allowUserPrinting: true,
  });
}

mergeWithSecurity(['invoice-1.pdf', 'invoice-2.pdf'], 'secured-invoices.pdf');

O userPassword é necessário para abrir o documento; o ownerPassword controla as próprias configurações de permissão. Definir allowUserPrinting: true enquanto desativa outros sinais de permissão permite que os destinatários imprimam o documento, mas impede a edição, cópia e anotação. Para uma lista completa de sinalizadores de permissão disponíveis, consulte a Referência API IronPDF Node.js.

Como mesclo PDFs e adiciono uma assinatura digital?

Mesclar PDFs e, em seguida, assinando imediatamente o resultado, produz um único documento assinado que cobre todo o conteúdo de origem. Aplique applySignature() após merge() para anexar um certificado digital à saída combinada.

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-with-signature.js
const IronPdf = require('ironpdf');

async function mergeAndSign(inputFiles, outputFile, pfxPath, pfxPassword) {
  const docs = await Promise.all(
    inputFiles.map(f => IronPdf.PdfDocument.fromFile(f))
  );
  const mergedPdf = await IronPdf.PdfDocument.merge(docs);

  // Attach a digital signature using a PFX certificate
  await mergedPdf.applySignature(pfxPath, pfxPassword);
  await mergedPdf.toFile(outputFile);
}

mergeAndSign(
  ['section-a.pdf', 'section-b.pdf'],
  'signed-report.pdf',
  'certificate.pfx',
  'certpass'
);

//:path=/static-assets/pdf/content-code-examples/how-to/nodejs-merge-pdf/merge-with-signature.js
const IronPdf = require('ironpdf');

async function mergeAndSign(inputFiles, outputFile, pfxPath, pfxPassword) {
  const docs = await Promise.all(
    inputFiles.map(f => IronPdf.PdfDocument.fromFile(f))
  );
  const mergedPdf = await IronPdf.PdfDocument.merge(docs);

  // Attach a digital signature using a PFX certificate
  await mergedPdf.applySignature(pfxPath, pfxPassword);
  await mergedPdf.toFile(outputFile);
}

mergeAndSign(
  ['section-a.pdf', 'section-b.pdf'],
  'signed-report.pdf',
  'certificate.pfx',
  'certpass'
);

O método applySignature() insere o certificado nos metadados do PDF para que os leitores possam verificar a integridade do documento. Este fluxo de trabalho é comum em pipelines de montagem de contratos, onde várias seções são combinadas e depois co-assinadas antes da distribuição. Para um tutorial completo sobre assinatura baseada em certificado, consulte os exemplos de assinaturas digitais.

Como solucionar erros comuns de mesclagem de PDFs?

A maioria dos erros durante a mesclagem se enquadra em quatro categorias: arquivos ausentes, esgotamento de memória, entradas corrompidas e problemas de permissão. A tabela abaixo lista as causas mais frequentes e como resolver cada uma.

Para problemas de configuração específicos do ambiente, o changelog do IronPDF documenta problemas conhecidos e correções. Se os problemas persistirem após verificar a tabela acima, envolva a chamada de mesclagem em um bloco try-catch para exibir a mensagem completa de erro da biblioteca.

O próprio Node.js fornece ferramentas úteis para validação de caminho antes do voo. O método Node.js fs.promises.access permite que você verifique se um arquivo é legível antes de passá-lo para o IronPDF. Para perguntas sobre como os desenvolvedores da comunidade lidam com cenários semelhantes de erro de mesclagem, o tópico Stack Overflow sobre mesclagem de PDFs no Node.js fornece contexto adicional.

Quais são os próximos passos para mesclar PDFs no Node.js?

Os exemplos acima cobrem os cenários de mesclagem mais comuns: combinação básica de arquivo, seleção de intervalo de páginas, injeção de cabeçalho e rodapé, proteção por senha e assinatura digital. IronPDF também suporta gerenciar formulários PDF em páginas mescladas, carimbar novo conteúdo no documento combinado e produzir imagens rasterizadas do resultado final para geração de visualizações.

Inicie seu teste gratuito de 30 dias para testar a mesclagem sem uma marca d'água, ou veja as opções de licenciamento se estiver pronto para implantar.

Pronto para ver o que mais o IronPDF pode fazer? Visite a documentação do IronPDF for Node.js para o tutorial completo da API e guias adicionais de como fazer.