Jak używać IronPdfEngine z Node.js
IronPdfEngine to serwer gRPC, który obsługuje wszystkie operacje PDF — tworzenie, edycję i odczyt — w imieniu klienta Node.js. Pakiet @ironsoftware/ironpdf jest cienką nakładką API, która komunikuje się z IronPdfEngine za pośrednictwem gRPC; każde wywołanie metody w Twoim kodzie Node.js jest wykonywane wewnątrz tego procesu serwera. Domyślnie, IronPDF dla Node.js uruchamia IronPdfEngine jako lokalny proces podrzędny, ale możesz również skierować go na zdalnie hostowaną instancję na potrzeby współdzielonych lub kontenerowych wdrożeń.
Szybki start: Konfiguracja IronPdfEngine dla Node.js
Zainstaluj pakiet, a IronPdfEngine uruchomi się automatycznie przy pierwszej operacji PDF:
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfMinimalny przebieg pracy (5 kroków)
- Zainstaluj pakiet Node.js IronPDF z
npm install @ironsoftware/ironpdf. - Podczas pierwszego uruchomienia, IronPDF wykrywa Twój platformę i pobiera odpowiednie pliki binarne IronPdfEngine.
- Dla wdrożeń offline lub szybszych uruchomień, zainstaluj pakiet silnika specyficzny dla platformy, taki jak
@ironsoftware/ironpdf-engine-windows-x64. - Sprawdź wymaganą wersję silnika za pomocą właściwości
IronPdfGlobalConfig.ironPdfEngineVersionprzed wdrożeniem zdalnej instancji. - Dla zdalnego silnika, wywołaj
IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" })przed dowolną operacją PDF.
Dlaczego IronPDF dla Node.js wymaga IronPdfEngine?
IronPDF dla Node.js nie zawiera samodzielnego renderera PDF. Pakiet Node.js jest klientem gRPC, a IronPdfEngine to serwer, który wykonuje rzeczywiste renderowanie, edycję i pracę z odczytem. Kiedy Twoja aplikacja wywołuje dowolną metodę IronPDF, żądanie podróżuje przez gRPC do procesu silnika, który zwraca wynik do Twojego kodu Node.js.
Ta architektura utrzymuje pakiet Node.js lekki i izoluje środowisko renderowania. Oznacza to również, że wersja silnika musi dokładnie pasować do wersji pakietu — nie są obsługiwane kombinacje między wersjami.
@ironsoftware/ironpdf wymaga tej samej wersji IronPdfEngine. Przed wdrożeniem jakiejkolwiek aktualizacji silnika należy sprawdzić zgodność, odczytując właściwość IronPdfGlobalConfig.ironPdfEngineVersion.Jak lokalnie uruchomić IronPdfEngine?
Lokalne wdrożenie to tryb domyślny. IronPDF dla Node.js uruchamia IronPdfEngine jako proces podrzędny przy starcie i komunikuje się z nim, aż do zamknięcia Twojej aplikacji. Dostępne są dwa podejścia instalacyjne, każde z różnymi kompromisami.
Opcja 1: Pobierz IronPdfEngine w czasie wykonania
Po zainstalowaniu @ironsoftware/ironpdf nie są wymagane żadne dodatkowe pakiety. Podczas pierwszego uruchomienia, IronPDF wykrywa platformę hosta (na przykład Windows x64) i pobiera dopasowane pliki binarne IronPdfEngine z internetu.
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfZalety:
- Utrzymuje mały pakiet aplikacji.
- Wdroża na wielu platformach bez konfiguracji specyficznej dla platformy.
Wady:
- Wymaga dostępu do internetu przy pierwszych kilku uruchomieniach.
- Wolniejszy czas uruchomienia przy pierwszym wykonaniu, podczas pobierania plików binarnych.
Opcja 2 (Zalecana): Zainstaluj IronPdfEngine jako zależność
IronPDF dla Node.js obsługuje pakiety silnika serwera, które zawierają plik binarny IronPdfEngine dla określonej platformy. Zainstaluj jeden lub więcej z tych pakietów wraz z główną biblioteką, aby wyeliminować pobieranie w czasie wykonania.
ironpdf i ironpdf-engine-xxx-xxx muszą być tej samej wersji. Numer wersji pakietu silnika odnosi się do wydania IronPDF, a nie do wewnętrznej wersji silnika.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-arm64Zalety:
- Szybszy start — brak konieczności pobrania w czasie działania.
- Brak konieczności dostępu do internetu po zainstalowaniu zależności.
Wady:
- Większy rozmiar pakietu aplikacji.
- Wymaga określenia docelowych platform w momencie budowy.
Jak połączyć się z zdalnym IronPdfEngine?
Zdalne wdrażanie jest odpowiednie, gdy generowanie PDF jest wspólną usługą – na przykład w kontenerowej architekturze mikrousług, klastrze Kubernetes, w którym wiele usług Node.js korzysta z jednego podu silnika lub w jakimkolwiek środowisku, w którym centralizacja procesu renderowania zmniejsza narzut na poziomie każdej usługi. Przed połączeniem, pobierz i uruchom obraz Dockera IronPdfEngine, postępując zgodnie z Jak pobrać i uruchomić IronPdfEngine.
Jak zweryfikować wymaganą wersję silnika?
Wersja silnika musi zgadzać się z wersją pakietu Node.js. Przeczytaj właściwość ironPdfEngineVersion, aby potwierdzić, którą wersję pobrać:
//: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}`);Użyj wydrukowanego numeru wersji przy określaniu tagu obrazu Dockera. Uruchomienie niezgodnej wersji spowoduje błędy komunikacji gRPC.
Jak skonfigurować połączenie zdalne?
Załóżmy, że IronPdfEngine działa w 123.456.7.8:33350. Umieść wywołanie konfiguracji na początku aplikacji — przed jakimkolwiek wywołaniem metody 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"
});Adres musi być dostępny z hosta Node.js. Sprawdź, czy żadna reguła zapory sieciowej nie blokuje portu 33350 między serwerem aplikacji a hostem silnika.
ironpdf-engine-xxx-xxx. Silnik lokalny jest całkowicie omijany po ustawieniu ironPdfEngineDockerAddress.Jakie są kolejne kroki?
Konfiguracja IronPdfEngine to podstawa dla wszystkich prac z PDF w Node.js. Gdy silnik jest uruchomiony – lokalnie lub zdalnie – pełne API IronPDF jest dostępne: konwertowanie HTML na PDF, scalanie dokumentów, dodawanie pieczątek i znaków wodnych, wyodrębnianie tekstu i więcej.
- Rozpocznij darmowy okres próbny, aby odblokować wszystkie funkcje bez znaków wodnych.
- Zakup licencję do wdrożeń produkcyjnych.
- Przejdź do pełnego samouczka wprowadzającego Node.js: IronPDF for Node.js — Getting Started.
Często Zadawane Pytania
Co to jest IronPdfEngine i dlaczego jest wymagany dla Node.js?
IronPdfEngine to serwer gRPC, który obsługuje wszystkie operacje renderowania, edycji i odczytu PDF. Pakiet for Node.js @ironsoftware/ironpdf jest biblioteką kliencką, która komunikuje się z IronPdfEngine za pomocą gRPC, więc silnik musi być uruchomiony — lokalnie lub zdalnie — aby jakakolwiek operacja PDF odniosła sukces.
Jak zainstalować IronPDF for Node.js?
Uruchom npm install @ironsoftware/ironpdf w katalogu projektu. Przy pierwszym uruchomieniu IronPDF wyczuje platformę hosta i automatycznie pobiera zgodne pliki binarne IronPdfEngine.
Jaka jest różnica między pobieraniem uruchomieni a opcjami zależności do pakietu?
Opcja pobierania uruchomieni nie wymaga dodatkowych pakietów, ale potrzebuje dostępu do internetu przy pierwszym uruchomieniu i ma wolniejsze uruchomienie początkowe. Opcja zależności do pakietu (Opcja 2, zalecana) instaluje specyficzny dla platformy pakiet, tak jak @ironsoftware/ironpdf-engine-windows-x64, który dołącza plik binarny silnika, więc uruchomienie jest szybsze i dostęp do internetu nie jest potrzebny po instalacji — kosztem większego pakiety.
Jak zapewnić, że wersja IronPdfEngine pasuje do mojej wersji pakietu IronPDF?
Odczytaj właściwość IronPdfGlobalConfig.ironPdfEngineVersion w czasie wykonywania, aby uzyskać dokładny wymagany ciąg wersji. Pakiet ironpdf i jakakolwiek zależność ironpdf-engine-xxx-xxx muszą mieć tę samą wersję; kombinacje między wersjami nie są obsługiwane.
Kiedy powinienem użyć zdalnego IronPdfEngine zamiast lokalnego?
Zdalny IronPdfEngine jest odpowiedni dla architektur mikroserwisowych konteneryzowanych, wdrożeń Kubernetes, gdzie wiele usług Node.js dzieli jedno renderujące pod, lub w każdym scenariuszu w którym centralizacja przetwarzania PDF redukuje zasoby dla każdej usługi.
Jak połączyć Node.js ze zdalnym IronPdfEngine?
Przy starcie aplikacji wywołaj IronPdfGlobalConfig.setConfig(ironPdfEngineDockerAddress: "host:port"), przed jakąkolwiek metodą IronPDF. Zamień host:port na adres IP zdalnego silnika i port (domyślnie 33350). Upewnij się, że adres jest dostępny i nie zablokowany przez firewall.
Czy muszę zainstalować pakiet zależności silnika używając zdalnego IronPdfEngine?
Nie. Kiedy ustawiono ironPdfEngineDockerAddress, IronPDF całkowicie omija lokalny silnik. Nie ma potrzeby instalacji jakiegokolwiek pakietu ironpdf-engine-xxx-xxx dla zdalnych wdrożeń.
Jakie platformy obsługuje IronPdfEngine?
Pakiety silnika specyficzne dla platformy są dostępne dla Windows x64, Windows x86, Linux x64, macOS x64, i macOS arm64. Zainstaluj pakiet pasujący do twojego docelowego wdrożenia, lub użyj opcji pobierania w czasie uruchomienia, aby obsłużyć wiele platform z jednej instalacji.
Czy mogę zainstalować kilka pakietów silników specyficznych dla platformy w tym samym projekcie?
Tak. Możesz zainstalować więcej niż jeden pakiet ironpdf-engine-xxx-xxx w tym samym projekcie. IronPDF wybiera poprawne binarium dla platformy hosta w czasie wykonywania, co jest przydatne w projektach, które budują i wdrażają na różnych systemach operacyjnych.
Jakiego portu używa IronPdfEngine do komunikacji gRPC?
IronPdfEngine nasłuchuje na porcie 33350 domyślnie. Kiedy konfigurujesz zdalne połączenie, uwzględnij ten port w wartości ironPdfEngineDockerAddress i zweryfikuj, że port jest otwarty między hostem Node.js a hostem silnika.
Wciąż przewijasz?
Czy chcesz szybko dowodu?
Uruchom przykład i zobacz, jak Twój kod HTML zamienia się w plik PDF.
Rozpocznij za DARMO
Rozpocznij za DARMO
Zarezerwuj darmowe Demo na żywo
Nie wymaga karty kredytowej ani tworzenia konta
