.png)
.svg){kind=icon}
14 de março de 2025
.
10
min ler
Guia completo para geração de PDF com Puppeteer: de documentos simples a relatórios complexos
Jorge Miloradovitch
Pesquisador, redator e entrevistador de casos de uso
Puppeteer é uma biblioteca Node.js que automatiza os navegadores Chrome ou Chromium, tornando-a uma ferramenta poderosa para criar PDFs. Quer você esteja criando documentos simples ou relatórios complexos, o Puppeteer oferece recursos como suporte nativo a PDF, layouts personalizados e integração de automação para agilizar o processo.
O Puppeteer é perfeito para automatizar fluxos de trabalho, gerar relatórios ou exportar conteúdo da web. De empresas criando documentos de marca a desenvolvedores lidando com visualizações de dados, o Puppeteer simplifica o processo e garante resultados de alta qualidade.
Se você estiver pronto para começar, o artigo explicará a configuração, a personalização e os recursos avançados, como lidar com relatórios grandes e solucionar problemas comuns.
O Latenode tem uma integração direta com um Headless Browser baseado no Puppeteer, que permite que você integre essa biblioteca aos seus cenários de automação para extrair dados de sites, fazer capturas de tela, converter arquivos e até mesmo automatizar serviços que não têm uma API.
Você pode adicionar código de qualquer complexidade, incluindo scripts para converter HTML em PDF. Depois que o nó estiver configurado, você pode vinculá-lo a muitas outras integrações para aprimorar sua automação: modelos de IA como ChatGPT, bancos de dados como Airtable, sistemas de CRM como Webflow e muitas outras integrações.
Comece a usar o Headless Browser agora para acelerar, aprimorar e simplificar seu trabalho!
Começar a usar o Puppeteer para criar PDFs envolve configurá-lo corretamente e entender suas opções básicas de configuração. Aqui está um guia rápido para ajudar você a começar.
Para gerar um PDF básico a partir de uma página da web, crie um app.js arquivo com o seguinte código:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://www.freecodecamp.org/', {
waitUntil: 'networkidle0'
});
await page.pdf({
path: 'example.pdf',
format: 'Letter'
});
await browser.close();
})();
Este script descreve o fluxo de trabalho essencial: iniciar um navegador, abrir uma página, navegar até um URL, gerar o PDF e fechar o navegador.
O Puppeteer permite que você ajuste várias configurações para criação de PDF. Abaixo estão algumas opções-chave que você pode modificar:
| Configuração | Descrição | Valor de exemplo |
|---|---|---|
| Formato | Tamanho do papel | 'Carta', 'A4', 'Ofício' |
| Largura | Largura de página personalizada | '8.5 pol.', '215.9 mm' |
| Altura | Altura de página personalizada | '11 pol.', '279.4 mm' |
| Paisagem | Orientação da página | verdadeiro falso |
| Margem | Margens da página | { superior: '1 pol.', direita: '1 pol.', inferior: '1 pol.', esquerda: '1 pol.' } |
Ao gerar PDFs de páginas da web, use o waitUntil: 'networkidle0' opção. Isso garante que toda a atividade de rede seja concluída antes que o PDF seja gerado.
Para conteúdo HTML personalizado, você pode criar PDFs usando arquivos locais. Isso é particularmente útil para documentos com modelo ou processamento em lote. Atualize o page.goto() funcionar assim:
await page.goto(`file://${absolutePath}`, {
waitUntil: 'networkidle0'
});
Como o Puppeteer depende do mecanismo de renderização do Chrome, qualquer estilo CSS ou formatação suportado pelo Chrome aparecerá com precisão em seus PDFs. Para necessidades mais complexas, você pode explorar técnicas avançadas de formatação para criar relatórios PDF detalhados.
O Puppeteer fornece muitas opções para personalizar seus PDFs. Confira as seções abaixo para aprender como configurar cabeçalhos, controlar o layout da página e manter seu design consistente.
Você pode incluir cabeçalhos e rodapés modificando as opções de PDF com modelos HTML. Aqui está um exemplo:
await page.pdf({
displayHeaderFooter: true,
headerTemplate: `<div style="font-size: 10px; padding: 10px; width: 100%; text-align: center;">
<span class="title"></span> | Generated on <span class="date"></span>
</div>`,
footerTemplate: `<div style="font-size: 10px; padding: 10px; width: 100%; text-align: center;">
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>`,
margin: { top: '1.25in', bottom: '1in' }
});
Aqui estão as classes dinâmicas que você pode usar:
Para gerenciar quebras de página e garantir que o conteúdo flua suavemente, use regras CSS como estas:
.no-break {
page-break-inside: avoid;
}
.force-break {
page-break-after: always;
}
Você também pode ajustar as configurações do papel diretamente nas opções de PDF:
| Configuração | Opções | Exemplo |
|---|---|---|
| Formato | Carta, A4, Legal | formato: 'Carta' |
| Dimensões | Largura/altura personalizada | largura: '8.5 pol', altura: '11 pol' |
| Orientação | Foto em paisagem | paisagem: verdadeiro |
| margens | Espaçamento personalizado | margem: { superior: '1 pol.', inferior: '1 pol.' } |
Ajuste fontes e recursos visuais para alinhá-los à sua marca:
@font-face {
font-family: 'CustomFont';
src: url('path/to/font.woff2') format('woff2');
}
await page.pdf({ printBackground: true });
body {
-webkit-print-color-adjust: exact;
background-color: #f5f5f5;
}
export FONTCONFIG_FILE=/path/to/fonts.conf
Essas opções permitem que você crie PDFs com aparência elegante e profissional.
Criar relatórios avançados em PDF requer atenção cuidadosa aos detalhes, especialmente quando se trata de visualização de dados, design de layout e desempenho. Ao aprimorar técnicas básicas de formatação, você pode produzir documentos de qualidade profissional que se destacam.
Melhore seus relatórios com visuais dinâmicos combinando Marionetista, D3.js e Guidão. Aqui está um exemplo de configuração para integrar gráficos de dados:
const template = Handlebars.compile(`
<div class="report-container">
{{> dataTable}}
<div id="chart"></div>
</div>
`);
// D3.js chart configuration
const chartConfig = {
container: '#chart',
data: salesData,
width: 800,
height: 400
};
Para garantir que seu PDF tenha uma aparência elegante, configure as configurações de saída da seguinte maneira:
await page.pdf({
printBackground: true,
format: 'Letter',
margin: {
top: '0.75in',
right: '0.5in',
bottom: '0.75in',
left: '0.5in'
}
});
"D3.js é uma biblioteca JavaScript para manipular documentos com base em dados. D3 ajuda você a dar vida aos dados usando HTML, SVG e CSS."
Depois que seus recursos visuais estiverem prontos, organize o relatório com conteúdo e números de página.
Siga estas etapas para adicionar um índice e garantir a numeração precisa das páginas:
const mainPdf = await page.pdf({
format: 'Letter',
displayHeaderFooter: true
});
const pageMapping = await extractPageNumbers(mainPdf);
const tocHtml = generateTocHtml(pageMapping);
const finalPdf = await mergePdfs([tocPdf, mainPdf]);
Para documentos maiores, você precisará tomar medidas adicionais para manter o desempenho.
Lidar com relatórios extensos de forma eficiente requer otimizações específicas. Aqui estão algumas técnicas eficazes:
| Técnica | Beneficiar |
|---|---|
| Uso de arquivo temporário | Reduz o uso de memória em 20% |
| Limitação do núcleo da CPU | Acelera o processamento equilibrando tarefas |
Por exemplo, nos Carriyo's a implementação em abril de 2024 gerou 10,000 PDFs diariamente com uma latência de 95º percentil de 365 ms no AWS Lambda. Veja como o tratamento temporário de arquivos pode ser aplicado:
// Optimize file handling
const tempFile = await saveTempHtml(content);
await page.goto(`file://${tempFile}`, {
waitUntil: 'networkidle0',
timeout: 30000
});
"Ao usar arquivos temporários para contornar as limitações do protocolo, melhoramos o desempenho e a confiabilidade." - Danindu de Silva
Se você encontrar problemas durante a navegação, certifique-se de registrar os erros e recarregar a página:
try {
await page.goto(url, {
waitUntil: 'networkidle0',
timeout: 30000
});
} catch (error) {
console.error('Navigation failed:', error);
await page.reload();
}
Esses métodos garantem que a geração de relatórios em larga escala permaneça confiável e eficiente.
Lidar com problemas comuns é essencial para garantir que seus fluxos de trabalho de PDF automatizados sejam executados de forma suave e confiável. As soluções a seguir se baseiam nos conceitos básicos de configuração discutidos anteriormente.
No Q3 de 2023, a equipe de desenvolvimento da Acme Corp abordou os erros "Failed to launch chrome" em servidores Ubuntu instalando as dependências necessárias. Isso reduziu as taxas de erro em 95% e economizou 10 horas por semana em tempo de depuração.
Para problemas de inicialização do Chrome no Windows, use a seguinte configuração:
const browser = await puppeteer.launch({
ignoreDefaultArgs: ['--disable-extensions'],
args: ['--disable-features=HttpsFirstBalancedModeAutoEnable']
});
Veja como lidar com erros comuns de forma eficiente:
| Tipo de Erro | Solução | Impacto |
|---|---|---|
| Módulo não encontrado | Atualizar Node.js para v14+ | Corrige conflitos de dependência |
| Tempo limite de navegação | Definir valores de tempo limite personalizados | Evita falhas prematuras de script |
| Problemas de sandbox | Ajustar permissões | Garante execução segura |
Por exemplo, para lidar com tempos limite de navegação, você pode usar esta lógica de repetição:
const navigateWithRetry = async (page, url) => {
try {
await page.goto(url, {
waitUntil: 'networkidle0',
timeout: 30000
});
} catch (error) {
console.error('Navigation error:', error);
await page.reload();
}
};
Depois que os erros forem resolvidos, você pode voltar sua atenção para melhorar a velocidade e obter mais eficiência no fluxo de trabalho.
Após lidar com erros, o próximo passo é aumentar a velocidade de geração de PDF. Por exemplo, a Carriyo gera 10,000 PDFs diariamente com uma latência p95 de 365 ms no AWS Lambda.
Aqui está um trecho de código para otimizar o desempenho disponibilizando ativos estáticos localmente:
await page.setRequestInterception(true);
page.on('request', request => {
if (request.resourceType() === 'font' || request.resourceType() === 'image') {
request.respond({
body: localFileContent,
headers: { 'Cache-Control': 'public, max-age=31536000' }
});
}
});
Para operações em larga escala, considere estas estratégias:
"Ao usar arquivos temporários para contornar as limitações do protocolo, melhoramos o desempenho e a confiabilidade." - Danindu de Silva
O Latenode facilita o uso do Puppeteer para gerar PDFs, oferecendo uma maneira escalável e econômica de automatizar fluxos de trabalho de documentos.
O Latenode combina os recursos de PDF do Puppeteer com ferramentas como um construtor de fluxo de trabalho visual, geração de código com tecnologia de IA e lógica condicional. Ele também oferece suporte a uma ampla gama de pacotes NPM. A plataforma usa um sistema de crédito baseado em tempo, que ajuda a gerenciar custos para automação de PDF de forma eficiente.
Com base na funcionalidade principal do Puppeteer, o Latenode simplifica fluxos de trabalho complexos de PDF com uma interface fácil de usar, projetada para escalabilidade.
Aqui estão os recursos de destaque para automação de PDF:
Para usar o Puppeteer para geração de PDF no Latenode, você pode seguir esta configuração básica:
const puppeteer = require('puppeteer');
async function generatePDF(url) {
const browser = await puppeteer.launch({
headless: true,
args: ['--disable-dev-shm-usage']
});
const page = await browser.newPage();
await page.goto(url, { waitUntil: 'networkidle0' });
const pdf = await page.pdf({ format: 'A4' });
await browser.close();
return pdf;
}
Para manter a geração de documentos segura, armazene informações confidenciais, como credenciais, em variáveis de ambiente:
await page.type('#email', process.env.PDF_USER);
await page.type('#password', process.env.PDF_PASSWORD);
Essa configuração garante um fluxo de trabalho seguro e eficiente para gerar PDFs.
Ao escolher uma plataforma para automação de PDF, veja como o Latenode se compara às ferramentas tradicionais:
| Característica | Nó latente | Ferramentas de automação tradicionais |
|---|---|---|
| Modelo de Preços | Créditos baseados em tempo a partir de US$ 5/mês | Licenciamento por documento ou baseado no usuário |
| Limites do fluxo de trabalho | 20–ilimitado | Frequentemente limitado por execuções simultâneas |
| Suporte ao pacote NPM | Mais de 1 milhão de pacotes | Geralmente limitado a módulos específicos da plataforma |
| Histórico de execução | Retenção por 1–60 dias | Muitas vezes limitado ao registro básico |
Para uso empresarial, o plano Prime da Latenode (US$ 297/mês) suporta até 1.5 milhão de execuções de cenário e retém o histórico de execução por 60 dias. Isso o torna uma escolha forte para empresas com necessidades de geração de PDF de alto volume.
A plataforma também simplifica tarefas como modificar o estilo da página antes de criar um PDF. Por exemplo, você pode ocultar elementos específicos com este snippet:
await page.addStyleTag({
content: '.nav { display: none } .navbar { border: 0px } #print-button { display: none }'
});
Essa flexibilidade ajuda a otimizar até mesmo os fluxos de trabalho de PDF mais complexos.
O Puppeteer é uma ferramenta poderosa para gerar PDFs, quer você esteja trabalhando com documentos simples ou relatórios complexos. Sua capacidade de lidar com tecnologias web modernas e fornecer controle refinado sobre a saída de PDF o torna uma escolha forte para casos de uso em larga escala.
Por exemplo, nos Carriyo usaram com sucesso o Puppeteer em abril de 2024 para gerar 10,000 PDFs diariamente para etiquetas de remessa no AWS Lambda. Eles alcançaram uma latência p95 de 365 ms a um custo de US$ 7.68 para 430,000 invocações.
Aqui estão alguns recursos de destaque e seus benefícios práticos:
| Característica | Beneficiar | Impacto no mundo real |
|---|---|---|
| Navegador sem cabeça | Permite renderização do lado do servidor com recursos modernos da web | Lida com conteúdo dinâmico, JavaScript e CSS com precisão |
| Otimização de Recursos | Armazena ativos em cache e desabilita recursos não utilizados para aumentar o desempenho | Melhora a eficiência durante a geração de PDF |
| Tratamento de erros | Inclui mecanismos de repetição e controles de tempo limite | Garante confiabilidade em ambientes de produção |
| Escalabilidade | Suporta geração de PDF de alto volume | Desempenho comprovado sob cargas de trabalho pesadas |
Para aproveitar ao máximo o Puppeteer, considere estas etapas para uma implantação bem-sucedida:
userDataDir configuração para armazenar recursos em cache e desabilitar recursos não utilizados para acelerar a geração de PDF.
Para uma experiência ainda mais tranquila, você pode integrar o Puppeteer com plataformas como o Latenode para simplificar os fluxos de trabalho e, ao mesmo tempo, manter o melhor desempenho.
