Comment utiliser IronPdfEngine avec Node.js
IronPdfEngine est un serveur gRPC qui gère toutes les opérations PDF — création, édition et lecture — au nom du client Node.js. Le package @ironsoftware/ironpdf est un wrapper API léger qui communique avec IronPdfEngine via gRPC ; chaque appel de méthode dans votre code Node.js est exécuté à l'intérieur de ce processus serveur. Par défaut, IronPDF for Node.js lance IronPdfEngine en tant que sous-processus local, mais vous pouvez également le diriger vers une instance hébergée à distance pour des déploiements partagés ou conteneurisés.
Démarrage rapide : Configurez IronPdfEngine for Node.js
Installez le package et IronPdfEngine s'exécute automatiquement lors de la première opération PDF :
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfFlux de travail minimal (5 étapes)
- Installez le package Node.js IronPDF avec
npm install @ironsoftware/ironpdf. - Lors de la première exécution, IronPDF détecte votre plateforme et télécharge les binaires IronPdfEngine appropriés.
- Pour des déploiements hors ligne ou à démarrage plus rapide, installez un package de moteur spécifique à la plateforme tel que
@ironsoftware/ironpdf-engine-windows-x64. - Vérifiez la version requise du moteur avec la propriété
IronPdfGlobalConfig.ironPdfEngineVersionavant de déployer une instance à distance. - Pour un moteur distant, appelez
IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" })avant toute opération PDF.
Pourquoi IronPDF for Node.js nécessite-t-il IronPdfEngine ?
IronPDF for Node.js ne regroupe pas un moteur de rendu PDF autonome. Le package Node.js est un client gRPC et IronPdfEngine est le serveur qui effectue réellement le rendu, l'édition et la lecture. Lorsque votre application appelle une méthode IronPDF, la requête voyage via gRPC jusqu'au processus du moteur, qui renvoie le résultat à votre code Node.js.
Cette architecture maintient le package Node.js léger et isole l'environnement de rendu. Cela signifie également que la version du moteur doit correspondre exactement à la version du package — les combinaisons inter-versions ne sont pas prises en charge.
@ironsoftware/ironpdf nécessite la même version d'IronPdfEngine. Vérifiez la compatibilité en consultant la propriété IronPdfGlobalConfig.ironPdfEngineVersion avant de déployer toute mise à jour du moteur.Comment exécuter IronPdfEngine localement ?
Le déploiement local est le mode par défaut. IronPDF for Node.js lance IronPdfEngine en tant que sous-processus au démarrage et communique avec lui jusqu'à la fermeture de votre application. Deux approches d'installation sont disponibles, chacune avec différents compromis.
Option 1 : Télécharger IronPdfEngine à l'exécution
Après l'installation de @ironsoftware/ironpdf, aucun autre package n'est requis. Lors de la première exécution, IronPDF détecte la plateforme hôte (par exemple, Windows x64) et télécharge les binaires IronPdfEngine correspondants depuis Internet.
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfAvantages :
- Maintient le package d'application petit.
- Déploie sur plusieurs plateformes sans configuration spécifique à la plateforme.
Inconvénients :
- Nécessite un accès Internet lors des premières exécutions.
- Temps de démarrage plus lent lors de la première exécution pendant que les binaires sont récupérés.
Option 2 (Recommandée) : Installez IronPdfEngine comme une Dépendance
IronPDF for Node.js prend en charge les packages de moteur dédiés qui regroupent le binaire IronPdfEngine pour une plateforme spécifique. Installez un ou plusieurs de ces packages à côté de la bibliothèque principale pour éliminer le téléchargement à l'exécution.
ironpdf et ironpdf-engine-xxx-xxx doivent être de la même version. Le numéro de version du package moteur fait référence à la version d'IronPDF, pas à la construction interne du moteur.Windows x64 :
//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x64Windows x86 :
//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x86//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x86Linux x64 :
//:path=shell
npm install @ironsoftware/ironpdf-engine-linux-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-linux-x64macOS x64 :
//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-x64macOS arm64 :
//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-arm64//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-arm64Avantages :
- Démarrage rapide — pas de téléchargement nécessaire à l'exécution.
- Aucun accès Internet requis après l'installation de la dépendance.
Inconvénients :
- Taille du package d'application plus grande.
- Nécessite la spécification des plateformes cibles au moment de la construction.
Comment vous connectez-vous à un IronPdfEngine distant ?
Le déploiement à distance est approprié lorsque la génération de PDF est un service partagé — par exemple, dans une architecture de microservices conteneurisée, un cluster Kubernetes où plusieurs services Node.js partagent un pod moteur, ou tout environnement où centraliser le processus de rendu réduit la surcharge par service. Avant de vous connecter, téléchargez et démarrez l'image Docker IronPdfEngine en suivant Comment Télécharger et Exécuter IronPdfEngine.
Comment vérifier la version requise du moteur ?
La version du moteur doit correspondre à la version du package Node.js. Lisez la propriété ironPdfEngineVersion pour confirmer la version à récupérer :
//:path=get-started/use-ironpdfengine/check-version.js
const ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);//:path=get-started/use-ironpdfengine/check-version.js
const ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);Utilisez le numéro de version imprimé lors de la spécification du tag d'image Docker. L'exécution d'une version incompatible entraînera des erreurs de communication gRPC.
Comment configurez-vous la connexion distante ?
Supposons qu'IronPdfEngine s'exécute à 123.456.7.8:33350. Placez l'appel de configuration au début de votre application — avant toute invocation de méthode IronPDF.
//:path=get-started/use-ironpdfengine/remote-config.js
IronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});//:path=get-started/use-ironpdfengine/remote-config.js
IronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});L'adresse doit être accessible depuis l'hôte Node.js. Vérifiez qu'aucune règle de pare-feu ne bloque le port 33350 entre le serveur d'applications et l'hôte du moteur.
ironpdf-engine-xxx-xxx. Le moteur de localisation est entièrement contourné une fois que ironPdfEngineDockerAddress est défini.Quelles sont les prochaines étapes?
Configurer IronPdfEngine est la base de tout travail PDF dans Node.js. Une fois que le moteur est en cours d'exécution — localement ou à distance — l'API complète IronPDF est disponible : convertir HTML en PDF, fusionner des documents, ajouter des tampons et des filigranes, extraire du texte, et plus encore.
- Commencez un essai gratuit pour débloquer toutes les fonctionnalités sans filigranes.
- Achetez une licence pour les déploiements en production.
- Continuez avec le tutoriel complet de démarrage Node.js : IronPDF for Node.js — Démarrez.
Questions Fréquemment Posées
Qu'est-ce que l'IronPdfEngine et pourquoi est-il requis for Node.js ?
IronPdfEngine est un serveur gRPC qui gère toutes les opérations de rendu, d'édition et de lecture de PDF. Le package Node.js @ironsoftware/ironpdf est un wrapper client qui communique avec IronPdfEngine via gRPC, de sorte que le moteur doit être en cours d'exécution — localement ou à distance — pour que toute opération PDF réussisse.
Comment installer IronPDF for Node.js ?
Exécutez npm install @ironsoftware/ironpdf dans le répertoire de votre projet. Lors de la première exécution, IronPDF détecte la plate-forme hôte et télécharge automatiquement les binaires correspondants de IronPdfEngine.
Quelle est la différence entre le téléchargement à l'exécution et les options de dépendance intégrée ?
L'option de téléchargement à l'exécution ne nécessite aucun package supplémentaire mais nécessite un accès à Internet lors de la première exécution et possède un démarrage initial plus lent. L'option de dépendance intégrée (Option 2, recommandée) installe un package spécifique à la plate-forme tel que @ironsoftware/ironpdf-engine-windows-x64, qui intègre le binaire du moteur pour un démarrage plus rapide et sans besoin d'accès à Internet après l'installation — au prix d'un package plus volumineux.
Comment puis-je m'assurer que la version d'IronPdfEngine correspond à la version de mon package IronPDF ?
Lisez la propriété IronPdfGlobalConfig.ironPdfEngineVersion à l'exécution pour obtenir la chaîne de version exacte requise. Le package ironpdf et toute dépendance ironpdf-engine-xxx-xxx doivent être de la même version ; les combinaisons de versions croisées ne sont pas supportées.
Quand devrais-je utiliser un IronPdfEngine distant au lieu d'un local ?
Un IronPdfEngine distant est approprié pour les architectures de microservices conteneurisés, les déploiements Kubernetes où plusieurs services Node.js partagent un seul pod de rendu, ou tout scénario où la centralisation du traitement PDF réduit la surcharge des ressources par service.
Comment connecter Node.js à un IronPdfEngine distant ?
Appelez IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" }) au début de votre application, avant toute méthode IronPDF. Remplacez host:port par l'adresse IP et le port du moteur distant (par défaut 33350). Assurez-vous que l'adresse est accessible et non bloquée par un pare-feu.
Ai-je besoin d'installer un package de dépendance moteur lors de l'utilisation d'un IronPdfEngine distant ?
Non. Lorsque ironPdfEngineDockerAddress est défini, IronPDF contourne tout moteur local. Il n'est pas nécessaire d'installer un package ironpdf-engine-xxx-xxx pour les déploiements à distance.
Quelles plateformes IronPdfEngine supporte-t-il ?
Des packages moteurs spécifiques à la plate-forme sont disponibles pour Windows x64, Windows x86, Linux x64, macOS x64 et macOS arm64. Installez le package correspondant à votre cible de déploiement, ou utilisez l'option de téléchargement à l'exécution pour prendre en charge plusieurs plates-formes à partir d'une seule installation.
Puis-je installer plusieurs packages de moteurs spécifiques à des plates-formes dans le même projet ?
Oui. Vous pouvez installer plus d'un package ironpdf-engine-xxx-xxx dans le même projet. IronPDF sélectionne le binaire approprié pour la plate-forme hôte à l'exécution, ce qui est utile pour les projets qui construisent et déploient sur plusieurs systèmes d'exploitation.
Quel port IronPdfEngine utilise-t-il pour la communication gRPC ?
IronPdfEngine écoute sur le port 33350 par défaut. Lors de la configuration d'une connexion distante, incluez ce port dans la valeur ironPdfEngineDockerAddress et vérifiez que le port est ouvert entre l'hôte Node.js et l'hôte moteur.
Vous faites encore défiler ?
Vous voulez une preuve rapidement ?
exécuter un échantillon Regardez votre code HTML se transformer en PDF.
Commencez GRATUITEMENT
Commencez GRATUITEMENT
Réservez une démonstration en direct gratuite
Aucune carte de crédit ou création de compte requise
