Pipeline przechodzi lokalnie, ale obraz pobrany na serwerze działa inaczej albo po kolejnym wdrożeniu zmienia zawartość. Oficjalny obraz Node.js z Docker Hub zwykle rozwiązuje problem szybkiego startu, o ile dobierzesz właściwy wariant i nie pomylisz wygodnego tagu ze stałą wersją.

Wybierz obraz Node.js pod sposób wdrożenia, nie pod sam rozmiar
- Na początek: dobierz konkretną linię Node.js i wariant systemu, zamiast polegać na samym tagu
latest. - Do produkcji: wybieraj wspieraną wersję LTS, a przy powtarzalnych wdrożeniach przypnij obraz do digestu.
- Debian slim: to rozsądny wariant dla aplikacji, które nie potrzebują narzędzi systemowych w obrazie końcowym.
- Alpine: obraz bywa mniejszy, ale używa biblioteki musl, co może utrudnić działanie natywnych zależności.
- Build wieloetapowy: pozwala oddzielić instalację i kompilację od uruchamiania aplikacji.
Oficjalny obraz Node.js oszczędza składania środowiska od zera
Gdy aplikacja ma działać tak samo na laptopie i w CI, bazowy obraz z Docker Hub daje gotowe środowisko z Node.js oraz npm. Oficjalne obrazy znajdziesz w repozytorium Node.js na Docker Hub; ich tag wskazuje wersję środowiska i często także wariant systemu, na przykład Debian albo Alpine.
Najprostszy test możesz wykonać poleceniem docker run --rm node:22 node --version, ale numer w przykładzie nie jest rekomendacją na kolejne lata. Dobieraj tag do wspieranej linii Node.js używanej przez projekt, a przed wdrożeniem sprawdź listę aktualnych tagów i architektur obrazu. Uważam, że właśnie rozróżnienie między tagiem „wygodnym” a tagiem „powtarzalnym” chroni przed większością przykrych niespodzianek.
Tag latest nie oznacza najnowszej wersji LTS
Tagi są etykietami wskazującymi obraz, a nie gwarancją, że za każdym pobraniem dostaniesz identyczną zawartość. Dokumentacja projektu obrazów Node.js opisuje node:lts jako ruchomy tag aktywnej wersji LTS, natomiast tag bez określonej linii wersji może wskazywać wydanie Current. Z kolei pominięcie tagu w komendzie oznacza użycie domyślnego latest.
W praktyce można rozdzielić trzy poziomy kontroli: node:lts dla wygodnego śledzenia aktywnego LTS, tag z konkretną wersją dla bardziej przewidywalnych aktualizacji oraz digest dla wskazania dokładnej zawartości obrazu. Sam numer wersji nie zawsze przypina wszystkie warstwy na zawsze, dlatego w krytycznym wdrożeniu użyj digestu i zaplanuj osobny proces aktualizacji. To szczegół, który najczęściej wychodzi na jaw dopiero przy różnicy między buildem lokalnym a produkcyjnym.
Debian slim i Alpine rozwiązują różne problemy
Mały obraz wygląda atrakcyjnie, dopóki aplikacja nie próbuje załadować natywnego modułu. Wariant slim zawiera ograniczony zestaw pakietów Debiana, a alpine bazuje na Alpine Linux i używa biblioteki musl zamiast glibc. Według dokumentacji obrazu Node.js, aplikacje przygotowane dla glibc mogą nie działać w środowisku musl, a Alpine może wymagać dodatkowych pakietów lub zmian.
Wybór uprości taka tabela:
| Sytuacja | Prawdopodobny skutek | Co zrobić |
|---|---|---|
| Aplikacja używa natywnych modułów npm, a zależności instalujesz w Debianie | Alpine może nie załadować binariów skompilowanych dla glibc | Wybierz wariant Debian, na przykład bookworm-slim, i testuj w obrazie końcowym |
| Chcesz zmniejszyć obraz, a aplikacja działa bez problemów na musl | Alpine może ograniczyć rozmiar, ale część narzędzi systemowych nie będzie dostępna | Przetestuj pełny build i start aplikacji na docelowej architekturze |
| Obraz służy do kompilacji, a nie do uruchamiania produkcyjnego | Narzędzia developerskie i kompilatory zwiększają końcowy obraz | Użyj osobnego etapu budowania i skopiuj do finalnego tylko potrzebne pliki |
Mniejszy obraz nie zawsze oznacza prostsze wdrożenie. Jeśli awaria zależności natywnej kosztuje więcej niż transfer kilku dodatkowych warstw, Debian slim jest rozsądniejszym punktem wyjścia.
Build wieloetapowy zostawia narzędzia poza produkcją
W projekcie z kompilacją TypeScript, bundlerem albo natywnymi zależnościami etap budowania potrzebuje więcej pakietów niż proces uruchamiający aplikację. Multi-stage build, czyli build wieloetapowy, pozwala użyć jednego obrazu do instalacji i kompilacji, a drugiego do startu gotowego programu. Docker opisuje taki podział jako typowy sposób wykorzystania lżejszego obrazu końcowego.
Przykład dla aplikacji Node.js, która buduje się do katalogu dist:
FROM node:22-bookworm AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/index.js"]
Ten schemat zakłada, że aplikacja uruchamia się z dist/index.js i nie wymaga plików spoza skopiowanych katalogów. Jeśli moduł natywny jest kompilowany w etapie build, oba etapy powinny korzystać ze zgodnej rodziny systemu i ABI; kopiowanie gotowych binariów z Alpine do Debiana może zakończyć się błędem. Wielostopniowość ogranicza zawartość finalnego obrazu, ale nie zwalnia z testowania go jako całości.
Przypięcie digestu daje powtarzalny punkt startu
Wyobraź sobie, że obraz z tagiem wersji buduje się dziś poprawnie, a po czasie ten sam pipeline pobiera pod tym tagiem inną zawartość. Tag może być przesuwany, podczas gdy digest identyfikuje konkretny obraz. Dokumentacja Dockera wyjaśnia, że przypięcie do digestu zapewnia pobranie tej samej wersji obrazu przy kolejnych buildach.
Przykładowa reguła jest prosta: jeśli budujesz lokalnie lub testujesz szybko, użyj tagu konkretnej wersji; jeśli wdrożenie ma być odtwarzalne, przypnij digest. Digest trzeba jednak aktualizować świadomie, bo w przeciwnym razie pipeline utrzyma także stare poprawki. Weryfikację dostępnych wariantów i identyfikatorów możesz wykonać narzędziem docker buildx imagetools inspect node:22-bookworm-slim; rezultat zależy od tagu dostępnego w danym momencie.
Najbezpieczniejszy wybór zaczyna się od zgodności zależności
Jeśli aplikacja nie ma szczególnych wymagań, zacznij od wspieranej wersji LTS na Debianie slim, zbuduj ją w osobnym etapie i sprawdź obraz końcowy w CI. Gdy zależności natywne i testy potwierdzą zgodność z musl, wtedy możesz rozważyć Alpine. Prawdę mówiąc, pogoń za najmniejszym rozmiarem obrazu rzadko jest dobrym pierwszym kryterium.
W repozytorium projektu trzymaj tag bazowy i digest w jednym miejscu, a aktualizację obrazu traktuj jak zmianę zależności: przetestuj build, uruchom testy aplikacji i dopiero potem wdrażaj. Właściwy obraz Node.js to ten, który daje powtarzalny build i uruchamia twoje zależności bez obejść, nawet jeśli nie jest najmniejszym tagiem na Docker Hub.
