Node.js und npm für den Build von Assets installieren

Node.js und npm sind in allen Hosting-Diensten verfügbar, um beim Build von Assets und beim Ausführen von Befehlen während der Deployments zu helfen. Dieses Werkzeug ist dafür gedacht, CSS/JavaScript zu bauen und Build-Befehle auszuführen, nicht dafür, Node.js-Anwendungen als Server zu betreiben.

Öffnen Sie im Kundenbereich den Abschnitt Hosting, wählen Sie den Hosting-Dienst, in dem Sie Node.js installieren möchten, und öffnen Sie den Abschnitt Paketmanager.

Node.js installieren

Wenn Node.js nicht installiert ist, sehen Sie eine Karte mit dem Status Nicht installiert und einem ausgeschalteten Schalter. Schalten Sie ihn ein, und das Node.js-Panel mit den aktuell verfügbaren Versionen öffnet sich.

Das Panel zeigt Ihnen, welche Version Sie wählen sollten, wenn Sie keine Präferenz haben; folgen Sie dieser Empfehlung, sofern die Eigenschaft engines.node Ihrer package.json keine andere verlangt. Prüfen Sie vor der Entscheidung auch den offiziellen Lebenszyklus von Node.js: LTS-Kennzeichnungen und Supportende ändern sich mit der Zeit, daher nennt diese Anleitung keine festen Versionsnummern.

EOL-Versionen sollten Sie weder für neue Projekte noch für normale Deployments verwenden. Falls das Panel eine davon für eine Migration bereithält, nutzen Sie sie nur vorübergehend, isoliert und ohne dauerhafte Dienste, mit einem festen Termin, um Abhängigkeiten zu aktualisieren und diese Umgebung zu entfernen.

Wählen Sie die Version und klicken Sie auf NVM und Node.js installieren mit der Versionsnummer. Der Vorgang installiert NVM (Node Version Manager), lädt Node.js herunter und installiert es, konfiguriert npm automatisch, ergänzt die Konfiguration in Ihrer .bashrc und prüft die Installation. Danach sehen Sie eine Erfolgsmeldung mit den installierten Versionen.

Version wechseln

Klicken Sie in der Karte Node.js des Paketmanagers auf Version ändern, wählen Sie die neue Version und klicken Sie auf Auf vX.x umstellen. Das System lädt die neue Version herunter, falls sie noch nicht installiert ist, legt sie als Standard fest und prüft, ob sie korrekt funktioniert.

Der Versionswechsel betrifft alle Projekte im selben Hosting-Dienst. Wenn Sie für verschiedene Projekte unterschiedliche Versionen brauchen, verwenden Sie nvm use manuell in Ihren Skripten.

Anwendungsbeispiele

Die Installation von Node.js ergänzt die nötige Konfiguration automatisch in Ihrer .bashrc. Dadurch ist Node.js in interaktiven SSH-Sitzungen und im Befehlsausführer des Panels verfügbar. In eigenen Deployment-Skripten und Cronjobs müssen Sie NVM jedoch manuell aktivieren, weil diese Kontexte .bashrc nicht automatisch laden.

Die Build-Beispiele setzen voraus, dass package.json und package-lock.json im Repository liegen und zueinander passen. Installieren oder aktualisieren Sie Abhängigkeiten in der Entwicklung, testen Sie das Ergebnis und speichern Sie beide Dateien. npm ci baut node_modules anhand der Lock-Datei neu auf; --include=dev bezieht die Build-Werkzeuge ein, auch wenn die Umgebung eine Produktionsumgebung ist.

Aus Deployment-Skripten

Der wichtigste Anwendungsfall ist die Kombination mit dem automatischen Deployment aus GitHub. Der Editor führt einen Befehl pro Zeile aus, und jede Zeile öffnet ihre eigene Shell: Aktivieren Sie NVM in derselben Zeile, die npm oder npx verwendet, nicht in einer separaten Zeile.

Laravel mit Vite:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run build

Laravel Mix:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run production

Projekt, in dem Tailwind CSS und seine CLI bereits als Abhängigkeiten deklariert sind:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify

WordPress mit eigenem Theme:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && cd wp-content/themes/mi-tema && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && cd wp-content/themes/mi-tema && npm run build

Per SSH und Befehlsausführer

Wenn Sie sich interaktiv per SSH verbinden oder den Befehlsausführer des Deployment-Panels verwenden, ist Node.js automatisch verfügbar, ohne dass Sie etwas exportieren müssen. Verbinden Sie sich per SSH oder nutzen Sie den Befehlsausführer und führen Sie direkt aus:

Assets manuell bauen:

cd /home/usuario/apps/mi-proyecto &&
npm ci --include=dev &&
npm run build

Tailwind CSS mit bereits deklarierten Abhängigkeiten bauen:

npm ci --include=dev
npx @tailwindcss/cli -i ./src/styles.css -o ./public/styles.css --minify

Bilder mit sharp optimieren, wenn das Projekt diese Abhängigkeit und das genannte Skript enthält:

npm ci --include=dev
node optimize-images.js

Tests ausführen:

npm ci --include=dev
npm test

TypeScript kompilieren, wenn es im Projekt deklariert und konfiguriert ist:

npm ci --include=dev
npx tsc

Deinstallation

Schalten Sie den Schalter der Karte Node.js aus und bestätigen Sie mit Node.js deinstallieren. Dadurch werden alle Node.js-Versionen, NVM, die in NVM gespeicherten globalen npm-Pakete und die NVM-Konfigurationszeilen in .bashrc entfernt. Die lokalen node_modules Ihrer Projekte werden dabei nicht gelöscht. Prüfen Sie vor der Deinstallation die Deployments und Cronjobs, die von Node abhängen.

Wichtige Einschränkungen

Dieses Werkzeug ist dafür gedacht, beim Deployment zu helfen, indem es Assets baut und Befehle ausführt, nicht dafür, Node.js-Anwendungen als Server zu betreiben. Gültige Anwendungsfälle sind etwa das Bauen von CSS/JavaScript mit PostCSS, Sass, Tailwind, Webpack, Vite oder Rollup, das Optimieren von Bildern, das Ausführen von Tests und das Erzeugen von Dokumentation. Sie können auch React, Vue oder eine andere statische Website mit einer externen API hosten: Nach dem Build liefert das Hosting nur ihre Dateien aus, und der Browser oder ein PHP-Backend kommunizieren per HTTPS mit der API.

Nicht geeignet ist es für Express-Server, Next.js im Servermodus, WebSocket-Server oder REST-APIs, die ständig laufen müssen. Dafür benötigen Sie eine Umgebung, die dauerhafte Node-Prozesse unterstützt und deren HTTP-Veröffentlichung, Neustart und Ports verwaltet. Die Installation von Node über diese Karte richtet einen solchen Dienst nicht ein; prüfen Sie die Kompatibilität Ihres Projekts, bevor Sie eine andere Umgebung bestellen.

Die dauerhaften Prozesse der Tarife Avanza, Max und Elastic halten Queue-Worker, Horizon oder eigene Befehle am Laufen, sind aber für Hintergrundaufgaben gedacht: Einen Node.js-Server oder andere Programme, die auf einem Port lauschen, unterstützen wir nicht. Wenn Sie WebSockets für eine Laravel-Anwendung brauchen, verbinden Sie sie mit einem Pusher-kompatiblen Dienst, wie in WebSockets in Laravel erklärt.

npm-Befehle unterliegen den CPU- und RAM-Limits des Hosting-Tarifs und den maximalen Laufzeiten des verwendeten Ausführers. Wenn Ihre Builds viele Ressourcen benötigen, bauen Sie lokal oder in einem CI/CD-System und laden Sie nur die gebauten Assets hoch. Einige npm-Pakete, die nativen Code kompilieren, können fehlschlagen, wenn sie nicht verfügbare Systemabhängigkeiten benötigen.

Fehlerbehebung

„NVM nicht gefunden“ oder „npm command not found“ in Deployment-Skripten: Laden Sie NVM in derselben Zeile, die npm oder npx verwendet, wie in den Deployment-Beispielen gezeigt. Wenn es auch in einer interaktiven Sitzung fehlt, prüfen Sie, ob NVM geladen wurde.

„npm command not found“ in interaktiver SSH-Sitzung: Prüfen Sie, ob Node.js im Paketmanager korrekt installiert ist. Wenn es installiert ist, aber nicht funktioniert, schließen Sie Ihre SSH-Sitzung und öffnen Sie sie erneut, damit .bashrc geladen wird, oder führen Sie source ~/.bashrc aus.

Sehr langsame Paketinstallation: Das erste npm install kann mehrere Minuten dauern, weil npm alle Abhängigkeiten herunterlädt. Der Cache kann spätere Downloads verringern, aber Build und Installationsskripte verbrauchen weiterhin Ressourcen.

Fehler „EACCES: permission denied“ beim Installieren eines globalen Pakets: Das bedeutet meist, dass NVM in dieser Shell nicht aktiv ist und npm versucht, außerhalb Ihres Kontos zu schreiben. Aktivieren Sie NVM mit . "$HOME/.nvm/nvm.sh" und wiederholen Sie den Vorgang; mit NVM werden globale Pakete in $HOME/.nvm installiert.

Die Node.js-Version stimmt nicht: Wenn node --version eine andere Version anzeigt, stellen Sie sicher, dass Sie die Standardversion im Paketmanager geändert haben, oder verwenden Sie nvm use VERSION, um vorübergehend zu wechseln.

Integration mit anderen Werkzeugen

Sie können Node.js mit dem automatischen Deployment aus GitHub nutzen, um Assets bei jedem Deployment automatisch zu bauen, ohne sie ins Repository hochzuladen. Composer und npm lassen sich im selben Deployment-Skript kombinieren:

composer install --no-dev --optimize-autoloader
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache

Sie können Node.js auch in Cronjobs für geplante Aufgaben verwenden. Wie in Deployment-Skripten müssen Sie NVM manuell aktivieren, weil Cronjobs .bashrc nicht laden:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && cd /home/usuario/public_html && node scripts/tarea.js

Führen Sie vor der Automatisierung einen Test-Build aus und prüfen Sie, ob das erwartete Verzeichnis erzeugt wird und die Website ihre Ressourcen lädt.