Como Usar o IronPdfEngine com Node.js
IronPdfEngine é um servidor gRPC que lida com todas as operações de PDF — criação, edição e leitura — em nome do cliente Node.js. O pacote @ironsoftware/ironpdf é um wrapper API fino que se comunica com o IronPdfEngine via gRPC; cada chamada de método no seu código Node.js é executada dentro desse processo de servidor. Por padrão, IronPDF for Node.js inicia o IronPdfEngine como um subprocesso local, mas você também pode apontá-lo para uma instância hospedada remotamente para implantações compartilhadas ou em contêiner.
Início rápido: Configurar o IronPdfEngine for Node.js
Instale o pacote e o IronPdfEngine será executado automaticamente na primeira operação de PDF:
npm e @ironsoftware/ironpdf
Fluxo de trabalho mínimo (5 etapas)
- Instale o pacote Node.js IronPDF com
npm install @ironsoftware/ironpdf. - Na primeira execução, o IronPDF detecta sua plataforma e baixa os binários corretos do IronPdfEngine.
- Para implantações offline ou de início rápido, instale um pacote de engine específico para a plataforma como
@ironsoftware/ironpdf-engine-windows-x64. - Verifique a versão necessária do engine com a propriedade
IronPdfGlobalConfig.ironPdfEngineVersionantes de implantar uma instância remota. - Para um engine remoto, chame
IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" })antes de qualquer operação de PDF.
Por Que o IronPDF for Node.js Requer o IronPdfEngine?
IronPDF for Node.js não inclui um renderizador de PDF independente. O pacote Node.js é um cliente gRPC e o IronPdfEngine é o servidor que realiza o trabalho real de renderização, edição e leitura. Quando sua aplicação chama qualquer método IronPDF, o pedido viaja pelo gRPC para o processo do engine, que retorna o resultado para o seu código Node.js.
Essa arquitetura mantém o pacote Node.js leve e isola o ambiente de renderização. Isso também significa que a versão do engine deve corresponder exatamente à versão do pacote — combinações de versões cruzadas não são suportadas.
@ironsoftware/ironpdf requer o IronPdfEngine da mesma versão. Verifique a compatibilidade lendo a propriedade IronPdfGlobalConfig.ironPdfEngineVersion antes de implantar qualquer atualização de mecanismo.Como Executar o IronPdfEngine Localmente?
A implantação local é o modo padrão. IronPDF for Node.js inicia o IronPdfEngine como um subprocesso na inicialização e se comunica com ele até que sua aplicação seja encerrada. Duas abordagens de instalação estão disponíveis, cada uma com prós e contras diferentes.
Opção 1: Baixar IronPdfEngine em Tempo de Execução
Após instalar @ironsoftware/ironpdf, não são necessários pacotes adicionais. Na primeira execução, o IronPDF detecta a plataforma do host (por exemplo, Windows x64) e baixa os binários correspondentes do IronPdfEngine da internet.
npm e @ironsoftware/ironpdf
Prós:
- Mantém o pacote da aplicação pequeno.
- Implanta em várias plataformas sem configuração específica para a plataforma.
Contras:
- Requer acesso à internet nas primeiras execuções.
- Tempo de início mais lento na execução inicial enquanto os binários são baixados.
Opção 2 (Recomendada): Instale o IronPdfEngine como uma Dependência
IronPDF for Node.js suporta pacotes de engine dedicados que contém o binário do IronPdfEngine para uma plataforma específica. Instale um ou mais desses pacotes junto com a biblioteca principal para eliminar o download em tempo de execução.
ironpdf e ironpdf-engine-xxx-xxx devem ser da mesma versão. O número da versão do pacote de engine refere-se ao lançamento do IronPDF, não à build interna do engine.Windows x64:
npm install @ironsoftware/ironpdf-engine-windows-x64
Windows x86:
npm install @ironsoftware/ironpdf-engine-windows-x86
Linux x64:
npm install @ironsoftware/ironpdf-engine-linux-x64
macOS x64:
npm install @ironsoftware/ironpdf-engine-macos-x64
macOS arm64:
npm install @ironsoftware/ironpdf-engine-macos-arm64
Prós:
- Início mais rápido — nenhum download é necessário em tempo de execução.
- Nenhum acesso à internet necessário após a instalação da dependência.
Contras:
- Maior tamanho do pacote da aplicação.
- Requer especificação de plataformas-alvo em tempo de build.
Como Conectar-se a um IronPdfEngine Remoto?
A implantação remota é apropriada quando a geração de PDF é um serviço compartilhado — por exemplo, em uma arquitetura de microsserviços em contêiner, um cluster Kubernetes onde múltiplos serviços Node.js compartilham um pod de engine, ou qualquer ambiente onde centralizar o processo de renderização reduz o overhead por serviço. Antes de conectar, extraia e inicie a imagem Docker do IronPdfEngine seguindo Como Extrair e Executar o IronPdfEngine.
Como Verificar a Versão Necessária do Engine?
A versão do engine deve coincidir com a versão do pacote Node.js. Leia a propriedade ironPdfEngineVersion para confirmar qual versão puxar:
:path=/static-assets/ironpdf-nodejs/content-code-examples/get-started/use-ironpdfengine-8.jsconst ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);
Use o número da versão impresso ao especificar a tag da imagem Docker. Executar uma versão incompatível causará erros de comunicação gRPC.
Como Configurar a Conexão Remota?
Pressuponha que o IronPdfEngine está sendo executado em 123.456.7.8:33350. Coloque a chamada de configuração no início do seu aplicativo — antes de qualquer invocação de método IronPDF.
:path=/static-assets/ironpdf-nodejs/content-code-examples/get-started/use-ironpdfengine-9.jsIronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});
O endereço deve ser acessível a partir do host Node.js. Verifique se nenhuma regra de firewall bloqueia a porta 33350 entre o servidor da aplicação e o host do mecanismo.
ironpdf-engine-xxx-xxx. O mecanismo local é completamente ignorado uma vez que ironPdfEngineDockerAddress é definido.Quais são os próximos passos?
Configurar o IronPdfEngine é a base para todo o trabalho com PDF no Node.js. Uma vez que o engine esteja funcionando — localmente ou remotamente — a API completa do IronPDF está disponível: converter HTML para PDF, mesclar documentos, adicionar marcas e marcas d'água, extrair texto, e muito mais.
- Inicie uma licença de teste gratuita para desbloquear todos os recursos sem marcas d'água.
- Compre uma licença para implantações em produção.
- Continue com o tutorial completo de início rápido do Node.js: IronPDF for Node.js — Iniciando.
Perguntas frequentes
O que é o IronPdfEngine e por que é necessário para Node.js?
IronPdfEngine é um servidor gRPC que lida com todas as operações de renderização, edição e leitura de PDF. O pacote Node.js @ironsoftware/ironpdf é um cliente que se comunica com o IronPdfEngine via gRPC, então o motor deve estar em execução — local ou remotamente — para que qualquer operação de PDF seja bem-sucedida.
Como faço para instalar o IronPDF for Node.js?
Execute npm install @ironsoftware/ironpdf no diretório do seu projeto. Na primeira execução, IronPDF detecta a plataforma host e baixa os binários IronPdfEngine correspondentes automaticamente.
Qual é a diferença entre a opção de download em tempo de execução e a opção de dependência agrupada?
A opção de download em tempo de execução não requer pacotes extras, mas precisa de acesso à internet na primeira execução e possui inicialização inicial mais lenta. A opção de dependência agrupada (Opção 2, recomendada) instala um pacote específico à plataforma como @ironsoftware/ironpdf-engine-windows-x64, que agrupa o binário do motor, tornando a inicialização mais rápida e eliminando a necessidade de acesso à internet após a instalação — ao custo de um pacote maior.
Como garanto que a versão do IronPdfEngine corresponda à versão do meu pacote IronPDF?
Leia a propriedade IronPdfGlobalConfig.ironPdfEngineVersion em tempo de execução para obter a string exata da versão exigida. O pacote ironpdf e qualquer pacote de dependência ironpdf-engine-xxx-xxx devem ser da mesma versão; combinações entre versões não são suportadas.
Quando devo usar um IronPdfEngine remoto em vez de um local?
Um IronPdfEngine remoto é apropriado para arquiteturas de microsserviço em contêineres, implantações Kubernetes onde vários serviços Node.js compartilham um único pod de renderização, ou em qualquer cenário onde centralizar o processamento de PDF reduz a sobrecarga de recursos por serviço.
Como conecto o Node.js a um IronPdfEngine remoto?
Chame IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" }) no início da sua aplicação, antes de qualquer método IronPDF. Substitua host:port pelo endereço IP e porta do motor remoto (padrão 33350). Certifique-se de que o endereço é acessível e não bloqueado por um firewall.
Preciso instalar um pacote de dependência de motor ao usar um IronPdfEngine remoto?
Não. Quando ironPdfEngineDockerAddress está configurado, IronPDF ignora qualquer motor local inteiramente. Não há necessidade de instalar qualquer pacote ironpdf-engine-xxx-xxx para implantações remotas.
Quais plataformas o IronPdfEngine suporta?
Pacotes de motor específicos da plataforma estão disponíveis para Windows x64, Windows x86, Linux x64, macOS x64 e macOS arm64. Instale o pacote correspondente ao seu alvo de implantação ou use a opção de download em tempo de execução para suportar múltiplas plataformas a partir de uma única instalação.
Posso instalar vários pacotes de motor específicos da plataforma no mesmo projeto?
Sim. Você pode instalar mais de um pacote ironpdf-engine-xxx-xxx no mesmo projeto. IronPDF seleciona o binário correto para a plataforma host em tempo de execução, o que é útil para projetos que são construídos e implantados em vários sistemas operacionais.
Qual porta o IronPdfEngine usa para comunicação gRPC?
IronPdfEngine escuta na porta 33350 por padrão. Ao configurar uma conexão remota, inclua esta porta no valor de ironPdfEngineDockerAddress e verifique se a porta está aberta entre o host Node.js e o host do motor.
Ainda está rolando a tela?
Quer provas rápidas?
executar um exemplo Veja seu HTML se transformar em um PDF.
Comece GRATUITAMENTE
Comece GRATUITAMENTE
Agende uma demonstração ao vivo gratuita
Não é necessário cartão de crédito nem criação de conta.
