Den Apple-Silicon-Build eines nativen Node.js-Moduls auf einem Cloud-Mac prüfen

Ein natives Node.js-Modul, das sich auf dem Entwicklungsrechner laden lässt, ist noch lange nicht zuverlässig auf einem Apple-Silicon-Cloud-Mac auslieferbar. Vorab kompilierte Dateien aus dem Cache, nicht in das Veröffentlichungspaket aufgenommene Build-Artefakte oder fehlerhafte Pfade zu dynamischen Bibliotheken können dazu führen, dass npm install scheinbar erfolgreich durchläuft, während das erste require() auf einem sauberen System fehlschlägt. Zuverlässiger ist eine durchgängige Abnahmekette aus Neuaufbau aus dem Quellcode, Binärprüfung, Paketprüfung und isolierter Installation.

Zuerst die Abnahmebasis festlegen

Erfassen Sie zunächst die Laufzeitumgebung, statt sofort den Cache zu leeren und alles neu zu installieren. Native Node.js-Module können N-API verwenden oder von einer bestimmten Modul-ABI abhängen; die jeweiligen Kompatibilitätsgrenzen unterscheiden sich. Das Projekt sollte die Node.js-Hauptversion über .nvmrc, .node-version oder CI-Parameter festlegen und zusätzlich die npm-Version protokollieren.

uname -m
sw_vers
node --version
npm --version
node -p "process.versions.napi || 'no-napi'"
node -p "process.versions.modules"
xcode-select -p
clang --version

In einer Apple-Silicon-Umgebung muss uname -m den Wert arm64 zurückgeben. Läuft bereits der Terminalprozess unter einer anderen Architektur, sind die nachfolgenden Build-Ergebnisse nicht repräsentativ für die Zielumgebung. Prüfen Sie außerdem, ob xcode-select -p auf die vorgesehene Toolchain verweist, damit die Kommandozeilenwerkzeuge nach einem Systemupdate nicht unbemerkt gewechselt haben.

Gegenstand der Abnahme ist nicht die Frage, ob das aktuelle Verzeichnis lauffähig ist, sondern ob sich aus dem Repository-Quellcode ein Artefakt für die Zielarchitektur erzeugen lässt, das vom endgültigen Veröffentlichungspaket geladen werden kann.

Neuaufbau aus dem Quellcode in einem sauberen Arbeitsbereich erzwingen

Führen Sie die Veröffentlichungsabnahme nicht in einem dauerhaft verwendeten Arbeitsverzeichnis durch. Checken Sie zuerst einen eindeutig bestimmten Commit aus und entfernen Sie anschließend das Abhängigkeitsverzeichnis sowie das Build-Verzeichnis des Moduls. Wenn Installationsskripte die .node-Datei erzeugen, muss das vollständige Installationsprotokoll aufbewahrt werden.

git status --short
git rev-parse HEAD
rm -rf node_modules build
npm cache verify
npm ci
npm rebuild --build-from-source

npm cache verify prüft lediglich die Cache-Struktur und belegt nicht, dass der Build ohne Cache erstellt wurde. Der entscheidende Schritt bleibt daher --build-from-source. Verfügt das Projekt über ein explizites Build-Skript, führen Sie zusätzlich npm run build aus, statt davon auszugehen, dass npm rebuild sämtliche Erzeugungsschritte abdeckt.

Bewahren Sie bei einem Fehler zunächst die vollständige Ausgabe auf und prüfen Sie danach Python, Compiler, SDK-Pfade und Headerdateien. Löschen Sie nicht beim ersten Fehler pauschal alle Caches. Eine undifferenzierte Bereinigung zerstört den Untersuchungsstand und verhindert die Zuordnung des Problems zur Toolchain, zum Quellcode oder zum Installationsskript.

N-API und Modul-ABI unterscheiden

Bei Modulen auf Basis von N-API sollte die deklarierte N-API-Mindestversion dokumentiert und ein Ladetest mit der vorgesehenen Node.js-Version ausgeführt werden. Erweiterungen, die direkt von der Modul-ABI abhängen, müssen in der Regel separat für die verschiedenen Node.js-Hauptversionen gebaut werden. Eine für eine bestimmte Version erzeugte Binärdatei darf nicht einfach für eine andere Version weiterverwendet werden.

Mach-O-Architektur und dynamische Abhängigkeiten prüfen

Ermitteln Sie nach Abschluss des Builds zunächst alle nativen Binärdateien. Prüfen Sie nicht nur die erste Datei in einem erwarteten Pfad.

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  xargs -0 file

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  while IFS= read -r -d '' binary; do
    echo "== $binary"
    lipo -info "$binary"
    otool -L "$binary"
  done

Wenn Apple Silicon die Zielplattform ist, muss jede zur Auslieferung bestimmte .node-Datei arm64 enthalten. Ein Universal Binary ist nur erforderlich, wenn der definierte Veröffentlichungsumfang ausdrücklich beide Architekturen abdeckt. Führen Sie nicht allein der Form halber zwei Slices zusammen, die nicht gleichwertig getestet wurden.

Mit otool -L sollten Sie insbesondere nach absoluten Pfaden des Entwicklungsrechners, temporären Verzeichnissen und benutzerdefinierten dynamischen Bibliotheken suchen, die nicht zusammen mit dem Paket ausgeliefert werden. Pfade zu System-Frameworks können in der Regel bestehen bleiben; Verweise auf persönliche Verzeichnisse oder Build-Arbeitsbereiche müssen vor der Veröffentlichung korrigiert werden. Enthält das Modul .dylib-Dateien, ist außerdem sicherzustellen, dass diese tatsächlich in der Paketliste enthalten sind und über verschiebbare Ladepfade eingebunden werden.

Das tatsächlich zu veröffentlichende npm-Paket abnehmen

Tests direkt im Quellcodeverzeichnis können nicht deklarierte Dateien, relative Pfade und zurückgebliebene Artefakte in den Ladevorgang einbeziehen. Erzeugen Sie vor der Veröffentlichung zunächst einen Tarball und installieren Sie ihn anschließend in einem leeren Verzeichnis.

rm -rf .package-check
mkdir .package-check

npm pack --json > .package-check/pack.json
PACKAGE_FILE="$(node -e "
const fs=require('fs');
const data=JSON.parse(fs.readFileSync('.package-check/pack.json','utf8'));
process.stdout.write(data[0].filename);
")"

tar -tzf "$PACKAGE_FILE"
cd .package-check
npm init -y >/dev/null
npm install "../$PACKAGE_FILE"
node -e "const addon=require('your-module'); console.log(typeof addon)"

Ersetzen Sie your-module durch den tatsächlichen Paketnamen und erweitern Sie die letzte Zeile um einen minimalen realen Funktionsaufruf. Der Smoke-Test muss mindestens eine native Funktion ausführen, statt lediglich die Existenz des JavaScript-Einstiegspunkts zu bestätigen. Wenn das Modul synchrone und asynchrone Schnittstellen anbietet, führen Sie beide jeweils einmal aus und prüfen Sie den Exit-Code des Prozesses.

Kontrollieren Sie zugleich die Ausgabe von tar -tzf: Lizenzdateien, Typdeklarationen, JavaScript-Einstiegspunkt, die vorgesehene .node-Datei und erforderliche dynamische Bibliotheken müssen enthalten sein. Quellcode-Caches, Testzugangsdaten, temporäre Protokolle und lokale Konfigurationen dürfen dagegen nicht in das Paket gelangen.

Häufige Fehler als Release-Gates abbilden

Teilen Sie die Abnahme nach Möglichkeit in voneinander unabhängige Fehlerbedingungen auf. So verhindert ein pauschales „Build fehlgeschlagen“ nicht die Ermittlung der eigentlichen Ursache:

1. Umgebungs-Gate: Bei Abweichungen zwischen Maschinenarchitektur, Node.js, npm, N-API oder ABI und den deklarierten Anforderungen wird der Ablauf gestoppt.
2. Neuaufbau-Gate: Nach dem Löschen vorhandener Artefakte muss der Build aus dem Quellcode erfolgreich sein und eine neue .node-Datei erzeugen.
3. Architektur-Gate: Jede auszuliefernde Binärdatei muss den Ziel-Slice arm64 enthalten.
4. Abhängigkeits-Gate: Verweise auf Arbeitsbereiche, persönliche Verzeichnisse oder nicht paketierte dynamische Bibliotheken sind unzulässig.
5. Paketinhalts-Gate: Maßgeblich ist das Ergebnis von npm pack, nicht der Inhalt des Quellcodeverzeichnisses.
6. Laufzeit-Gate: Der Tarball wird in einem isolierten Verzeichnis installiert und mindestens ein nativer API-Aufruf ausgeführt.

Wenn Sie diesen Ablauf auf DPLYMAC ausführen, können Sie die Umgebungsdaten, den Commit-Hash, die Prüfsumme des Tarballs und die Ausgabe des Smoke-Tests für jeden Auftrag als gemeinsamen Build-Nachweis speichern. So lässt sich auch nach späteren Upgrades von Node.js oder der Compiler-Toolchain feststellen, ob eine Abweichung in der Umgebung, beim Kompilieren, beim Paketieren oder zur Laufzeit entstanden ist.

Die endgültigen Auslieferungskriterien sollten einfach sein: Ein sauberer Checkout lässt sich neu bauen, die Binärarchitektur ist korrekt, die dynamischen Abhängigkeiten sind verschiebbar, der Paketinhalt ist vollständig und das Veröffentlichungspaket kann in einer isolierten Umgebung einen realen Aufruf ausführen. Erst wenn alle fünf Punkte erfüllt sind, hat das native Modul die Apple-Silicon-Abnahme bestanden.

Häufig gestellte Fragen