Obraz Dockera Next.js z wyjściem: „samodzielny”: kompilacja wieloetapowa i proces inny niż root
Dlaczego samodzielny
Zwykły obraz Next.js kopiuje cały node_modules wraz z zależnościami deweloperskimi, źródłami i pamięcią podręczną kompilacji. Dzięki output: 'standalone' Next.js po zbudowaniu śledzi, które pliki są rzeczywiście potrzebne serwerowi i umieszcza je w .next/standalone wraz z minimalnym server.js. Tylko to, statyczne i public ląduje na ostatecznym obrazie.
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;W monorepozytorium dodaj outputFileTracingRoot ze ścieżką do katalogu głównego repozytorium, w przeciwnym razie śledzenie nie znajdzie pakietów z sąsiednich folderów.
Plik Dockera
[[VB_1_KOD]]
Analiza rozwiązań:
- Trzy etapy. Kompilatory, zależności deweloperskie i źródła pozostają na etapach pośrednich i nie trafiają do ostatecznego obrazu.
- `--mount=type=cache` zachowuje pamięć podręczną npm pomiędzy kompilacjami na tej samej maszynie. Jest to funkcja BuildKit, stąd linia
# syntaxna początku. - `HOSTNAME=0.0.0.0`.
server.jsnasłuchuje adresu z tej zmiennej. Bez tego serwer może powiązać się z nazwą kontenera, a przekierowany port odpowie komunikatem o błędzie połączenia. - Statyki są kopiowane osobno.
.next/standalonenie zawiera.next/staticipublic- jest to częsta przyczyna 404 w CSS i JS po pierwszej kompilacji. - `USER node`. Oficjalne obrazy Node mają już nieuprzywilejowanego użytkownika
node(uid 1000). Nie jest konieczne tworzenie własnego, ale pliki muszą zostać skopiowane z--chown, w przeciwnym razie proces nie będzie mógł zapisać w.next/cachew celu ISR i optymalizacji obrazu.
Zmienne środowiskowe: kompilacja i środowisko wykonawcze
Zmienne NEXT_PUBLIC_* są zastępowane w JavaScript klienta podczas next build. Jest już za późno na ich transfer za pomocą docker run - paczka zawiera już wartość z zestawu lub jest pusta. Dlatego przechodzą przez ARG na etapie konstruktora.
Wręcz przeciwnie, sekrety serwera (DATABASE_URL, klucze API) nie powinny być uwzględniane w obrazie. Nie przekazuj ich jako ARG i nie kopiuj .env - ustaw je przy starcie:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
I pamiętaj o .dockerignore, w przeciwnym razie COPY . . przeciągnie niepotrzebne rzeczy do kontekstu asemblera, w tym sekrety:
node_modules .next .git .env* *.log coverage
PID 1 i zatrzymanie kontenera
Proces węzła działający jako PID 1 nie otrzymuje standardowego zachowania jądra dla sygnałów. Jeśli aplikacja nie ma procedury obsługi SIGTERM, docker stop czeka na przekroczenie limitu czasu (domyślnie 10 sekund) i zabija proces poprzez SIGKILL, kończąc aktywne żądania. Prostym rozwiązaniem jest proces init:
[[VB_4_KOD]]
Wąski obraz nie zawiera curl, więc kontrola stanu jest zapisana w samym węźle: globalny fetch jest dostępny w węźle 18 i nowszych.
Obrazy i ostre
W Next.js 15 sharp jest automatycznie łączony z next start iw trybie autonomicznym; nie ma potrzeby instalowania go ręcznie. Jeśli nadal widzisz ostrzeżenie o braku Sharpa, sprawdź, czy kompilacja i środowisko wykonawcze znajdują się na tej samej platformie: pliki binarne skompilowane dla glibc nie działają na Alpine (musl) i odwrotnie. Dlatego w tym przykładzie wszystkie etapy pochodzą z jednego podstawowego obrazu.
Jak sprawdzić wynik
[[VB_5_KOD]]
Do analizy tego, co zajmuje miejsce w warstwach, wygodne jest narzędzie dive. Jeśli końcowy obraz jest nieoczekiwanie duży, zwykle zawiera cały node_modules: sprawdź, czy w prowadnicy nie ma COPY . ..
Typowe błędy
Error: EACCESpodczas zapisu do.next/cache- pliki zostały skopiowane bez--chown.- Strona działa, ale bez stylów - zapomnieli skopiować
.next/static. NEXT_PUBLIC_*pusty w przeglądarce - przesyłany w czasie wykonywania, a nie podczas montażu.- Zbuduj na Macu z Apple Silicon, uruchom na serwerze amd64 - potrzebujesz
docker buildx build --platform linux/amd64, w przeciwnym razie natywne moduły mają niewłaściwą architekturę.
Gdy samodzielny nie jest potrzebny
Jeśli wdrożenie trafi na Vercel lub inną platformę z własnym zestawem, to ustawienie nic nie daje. Do eksportu statycznego (output: 'export') serwer w ogóle nie jest potrzebny - wystarczy nginx ze statycznym.