---
title: Multi-stage et cache de build
description: Accélérer les builds et réduire la taille de l'image finale.
---

## Le modèle de couches

Chaque instruction d'un Dockerfile produit une couche. Au prochain build, Docker réutilise une couche mise en cache tant que ses entrées n'ont pas changé.

<Callout title="Règle du cache" type="warning">
  Le cache fonctionne comme un préfixe : dès qu'une couche est invalidée, toutes les couches suivantes doivent être reconstruites.
</Callout>

## Ce qui invalide une couche

| Instruction | Le cache saute si… |
| --- | --- |
| `FROM node:25-slim` | Le digest de l'image de base change |
| `COPY package.json ./` | Le contenu du fichier copié change |
| `RUN npm ci` | La commande ou une couche précédente change |
| `COPY . .` | N'importe quel fichier du contexte change |

`COPY` compare le contenu, pas seulement la date. Avec `COPY . .`, le moindre changement dans le contexte invalide cette couche.

## Ordonner du plus stable au plus volatil

```dockerfile
FROM node:25-slim AS builder
WORKDIR /app

# Les manifestes changent rarement
COPY package.json package-lock.json ./
RUN npm ci

# Le code change souvent
COPY . .
RUN npm run build
```

Si un fichier TypeScript change, les couches `COPY package.json` et `RUN npm ci` restent en cache. Seules la copie du code et la compilation sont rejouées.

À l'inverse, placer `COPY . .` avant `npm ci` provoquerait une réinstallation complète des dépendances à chaque changement de code.

## Stabiliser le contexte avec .dockerignore

```text
node_modules
dist
.git
*.log
```

Sans ce fichier, des dossiers locaux volumineux peuvent être envoyés au daemon et invalider le cache inutilement.

## Séparer la compilation du runtime

Un build multi-stage utilise plusieurs instructions `FROM`. Le premier stage contient les outils de compilation ; le second repart d'une image propre et ne récupère que le résultat.

```dockerfile
# Stage 1 - builder
FROM node:25-slim AS builder
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

# Stage 2 - runtime
FROM node:25-slim
WORKDIR /app

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

CMD ["node", "dist/src/main"]
```

## Deux bénéfices distincts

| Bénéfice | Explication |
| --- | --- |
| Image finale plus petite | Les sources, les caches et l'outillage du builder ne sont pas copiés dans le runtime. |
| Caches séparés | Le stage de build conserve son cache de dépendances ; le stage final ne change que si les artefacts changent. |

<Callout title="Aller plus loin" type="idea">
  Copier node_modules depuis le builder embarque aussi les devDependencies. Pour une image plus légère, le stage final peut exécuter un npm ci --omit=dev dédié.
</Callout>
