Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation de la spécification de déploiement d'Amplify Hosting pour configurer la sortie de compilation

La spécification de déploiement d'Amplify Hosting est une spécification basée sur un système de fichiers qui définit la structure de répertoire qui facilite les déploiements vers Amplify Hosting. Un framework peut générer cette structure de répertoire attendue en sortie de sa commande de construction, ce qui lui permet de tirer parti des primitives de service d'Amplify Hosting. Amplify Hosting comprend la structure du bundle de déploiement et le déploie en conséquence.

Pour une démonstration vidéo expliquant comment utiliser les spécifications de déploiement, consultez Comment héberger un site Web via AWS Amplify le YouTube canal Amazon Web Services.

Voici un exemple de la structure de dossiers qu'Amplify attend pour le bundle de déploiement. À un niveau élevé, il possède un dossier nomméstatic, un dossier nommé compute et un fichier manifeste de déploiement nommédeploy-manifest.json.

.amplify-hosting/
├── compute/
│   └── default/
│       ├── chunks/
│       │   └── app/
│       │       ├── _nuxt/
│       │       │   ├── index-xxx.mjs
│       │       │   └── index-styles.xxx.js
│       │       └── server.mjs
│       ├── node_modules/
│       └── server.js
├── static/
│   ├── css/
│   │   └── nuxt-google-fonts.css
│   ├── fonts/
│   │   ├── font.woff2
│   ├── _nuxt/
│   │   ├── builds/
│   │   │   └── latest.json
│   │   └── entry.xxx.js
│   ├── favicon.ico
│   └── robots.txt
└── deploy-manifest.json

Amplifier SSR le support primitif

La spécification de déploiement d'Amplify Hosting définit un contrat qui correspond étroitement aux primitives suivantes.

Le .amplify-hosting/static directory

Vous devez placer dans le .amplify-hosting/static répertoire tous les fichiers statiques accessibles au public destinés à être servis par l'applicationURL. Les fichiers contenus dans ce répertoire sont servis via la primitive static assets.

Les fichiers statiques sont accessibles à la racine (/) de l'application URL sans modification de leur contenu, de leur nom de fichier ou de leur extension. De plus, les sous-répertoires sont conservés dans la URL structure et apparaissent avant le nom du fichier. À titre d'exemple, .amplify-hosting/static/favicon.ico sera servi depuis https://myAppId.amplify-hostingapp.com/favicon.ico et .amplify-hosting/static/_nuxt/main.js sera servi depuis https://myAppId.amplify-hostingapp.com/_nuxt/main.js

Si un framework permet de modifier le chemin de base de l'application, il doit ajouter le chemin de base aux actifs statiques du .amplify-hosting/static répertoire. Par exemple, si le chemin de base est/folder1/folder2, la sortie de génération pour un actif statique appelé main.css sera.amplify-hosting/static/folder1/folder2/main.css.

Le .amplify-hosting/compute directory

Une ressource de calcul unique est représentée par un sous-répertoire unique nommé default contenu dans le .amplify-hosting/compute répertoire. Le chemin est.amplify-hosting/compute/default. Cette ressource de calcul correspond à la primitive de calcul d'Amplify Hosting.

Le contenu du default sous-répertoire doit être conforme aux règles suivantes.

Amplify Hosting regroupe et déploie tous les fichiers du default sous-répertoire vers une ressource de calcul provisionnée. Chaque ressource de calcul se voit attribuer 512 Mo de stockage éphémère. Ce stockage n'est pas partagé entre les instances d'exécution, mais est partagé entre les invocations suivantes au sein de la même instance d'exécution. Les instances d'exécution sont limitées à une durée d'exécution maximale de 15 minutes, et le seul chemin accessible en écriture au sein de l'instance d'exécution est le /tmp répertoire. La taille compressée de chaque ensemble de ressources de calcul ne peut pas dépasser 220 Mo. Par exemple, le .amplify/compute/default sous-répertoire ne peut pas dépasser 220 Mo lorsqu'il est compressé.

Le .amplify-hosting/deploy-manifest.json dans le fichier

Utilisez le deploy-manifest.json fichier pour stocker les détails de configuration et les métadonnées d'un déploiement. Au minimum, un deploy-manifest.json fichier doit inclure un version attribut, l'routesattribut avec une route fourre-tout spécifiée et l'frameworkattribut avec des métadonnées de structure spécifiées.

La définition d'objet suivante illustre la configuration d'un manifeste de déploiement.

type DeployManifest = {
  version: 1;
  routes: Route[];
  computeResources?: ComputeResource[];
  imageSettings?: ImageSettings;
  framework: FrameworkMetadata;
};

Les rubriques suivantes décrivent les détails et l'utilisation de chaque attribut du manifeste de déploiement.

Utilisation de l'attribut version

L'versionattribut définit la version de la spécification de déploiement que vous implémentez. Actuellement, la seule version pour la spécification de déploiement d'Amplify Hosting est la version 1. L'JSONexemple suivant illustre l'utilisation de l'versionattribut.

"version": 1

Utilisation de l'attribut routes

L'routesattribut permet aux frameworks de tirer parti de la primitive des règles de routage d'Amplify Hosting. Les règles de routage fournissent un mécanisme pour acheminer les chemins des demandes entrantes vers une cible spécifique du bundle de déploiement. Les règles de routage dictent uniquement la destination d'une demande entrante et sont appliquées une fois que la demande a été transformée par des règles de réécriture et de redirection. Pour plus d'informations sur la façon dont Amplify Hosting gère les réécritures et les redirections, consultez. Configuration des redirections et des réécritures pour une application Amplify

Les règles de routage ne réécrivent ni ne transforment la demande. Si une demande entrante correspond au modèle de chemin d'un itinéraire, la demande est acheminée telle quelle vers la cible de l'itinéraire.

Les règles de routage spécifiées dans le routes tableau doivent être conformes aux règles suivantes.

La définition d'objet suivante illustre la configuration de l'Routeobjet.

type Route = {
  path: string;
  target: Target;
  fallback?: Target;
}

Le tableau suivant décrit les propriétés de l'Routeobjet.

La définition d'objet suivante illustre la configuration de l'Targetobjet.

type Target = {
  kind: TargetKind;
  src?: string;
  cacheControl?: string;
}

Le tableau suivant décrit les propriétés de l'Targetobjet.

La définition d'objet suivante illustre l'utilisation de l'TargetKindénumération.

enum TargetKind {
  Static = "Static",
  Compute = "Compute",
  ImageOptimization = "ImageOptimization"
}

La liste suivante indique les valeurs valides pour l'TargetKindénumération.

L'JSONexemple suivant illustre l'utilisation de l'routesattribut avec plusieurs règles de routage spécifiées.

"routes": [
    {
      "path": "/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ]

Pour plus d'informations sur la spécification des règles de routage dans votre manifeste de déploiement, voir Bonnes pratiques pour configurer les règles de routage

Utilisation de l'computeResourcesattribut

L'computeResourcesattribut permet aux frameworks de fournir des métadonnées sur les ressources de calcul allouées. Chaque ressource de calcul doit être associée à un itinéraire correspondant.

La définition d'objet suivante illustre l'utilisation de l'ComputeResourceobjet.

type ComputeResource = {
  name: string;
  runtime: ComputeRuntime;
  entrypoint: string;
};

type ComputeRuntime = 'nodejs16.x' | 'nodejs18.x' | 'nodejs20.x';

Le tableau suivant décrit les propriétés de l'ComputeResourceobjet.

Si vous avez une structure de répertoire qui ressemble à la suivante.

.amplify-hosting
|---compute
|   |---default
|       |---index.js

L'computeResourceattribut JSON for ressemblera à ce qui suit.

"computeResources": [
    {
      "name": "default",
      "runtime": "nodejs16.x",
      "entrypoint": "index.js",
    }
  ]

Utilisation de l' imageSettings attribut

L'imageSettingsattribut permet aux frameworks de personnaliser le comportement de la primitive d'optimisation d'image, qui fournit une optimisation à la demande des images lors de l'exécution.

La définition d'objet suivante illustre l'utilisation de l'ImageSettingsobjet.

type ImageSettings = {
  sizes: number[];
  domains: string[];
  remotePatterns: RemotePattern[];
  formats: ImageFormat[];
  minumumCacheTTL: number;
  dangerouslyAllowSVG: boolean;
};

type ImageFormat = 'image/avif' | 'image/webp' | 'image/png' | 'image/jpeg';

Le tableau suivant décrit les propriétés de l'ImageSettingsobjet.

La définition d'objet suivante illustre l'utilisation de l'RemotePatternobjet.

type RemotePattern = {
  protocol?: 'http' | 'https';
  hostname: string;
  port?: string;
  pathname?: string;
}

Le tableau suivant décrit les propriétés de l'RemotePatternobjet.

L'exemple suivant illustre l'imageSettingsattribut.

"imageSettings": { 
    "sizes": [
      100,
      200
    ],
    "domains": [
      "example.com"
    ],
    "remotePatterns": [
      {
        "protocol": "https",
        "hostname": "example.com",
        "port": "",
        "pathname": "/**",
      }
    ],
    "formats": [
      "image/webp"
    ],
    "minumumCacheTTL": 60,
    "dangerouslyAllowSVG": false
  }

Utilisation de l'attribut framework

Utilisez l'frameworkattribut pour spécifier les métadonnées du framework.

La définition d'objet suivante illustre la configuration de l'FrameworkMetadataobjet.

type FrameworkMetadata = {
  name: string;
  version: string;
}

Le tableau suivant décrit les propriétés de l'FrameworkMetadataobjet.

Bonnes pratiques pour configurer les règles de routage

Les règles de routage fournissent un mécanisme pour acheminer les chemins des demandes entrantes vers des cibles spécifiques du bundle de déploiement. Dans un bundle de déploiement, les auteurs du framework peuvent émettre des fichiers vers la sortie de build qui sont déployés sur l'une des cibles suivantes :

Les auteurs du framework fournissent également un ensemble de règles de routage dans le fichier manifeste de déploiement. Chaque règle du tableau est comparée à la demande entrante dans un ordre séquentiel, jusqu'à ce qu'il y ait une correspondance. Lorsqu'il existe une règle de correspondance, la demande est acheminée vers la cible spécifiée dans la règle de correspondance. Facultativement, une cible de secours peut être spécifiée pour chaque règle. Si la cible d'origine renvoie une erreur 404, la demande est acheminée vers la cible de secours.

La spécification de déploiement exige que la dernière règle de l'ordre de traversée soit une règle fourre-tout. Une règle fourre-tout est spécifiée avec le /* chemin. Si la demande entrante ne correspond à aucune des routes précédentes du tableau de règles de routage, elle est acheminée vers la cible de règles fourre-tout.

Pour des SSR frameworks tels que Nuxt.js, la cible de la règle fourre-tout doit être la primitive de calcul. Cela est dû au fait que SSR les applications ont des pages affichées côté serveur avec des itinéraires qui ne sont pas prévisibles au moment de la création. Par exemple, si un Nuxt.js l'application possède une page /blog/[slug] où se [slug] trouve un paramètre de route dynamique. La cible de la règle fourre-tout est le seul moyen d'acheminer les demandes vers ces pages.

En revanche, des modèles de trajectoire spécifiques peuvent être utilisés pour cibler des itinéraires connus au moment de la construction. Par exemple, Nuxt.js fournit des actifs statiques à partir du /_nuxt chemin. Cela signifie que le /_nuxt/* chemin peut être ciblé par une règle de routage spécifique qui achemine les demandes vers la primitive des actifs statiques.

Routage des dossiers publics

La plupart SSR des frameworks offrent la possibilité de servir des actifs statiques mutables à partir d'un public dossier. Les fichiers tels que favicon.ico et robots.txt sont généralement conservés dans le public dossier et sont servis à partir de la racine de l'applicationURL. Par exemple, le favicon.ico fichier est servi à partir dehttps://example.com/favicon.ico. Notez qu'il n'existe aucun modèle de chemin prévisible pour ces fichiers. Ils sont presque entièrement dictés par le nom du fichier. La seule façon de cibler les fichiers contenus dans le public dossier est d'utiliser la méthode fourre-tout. Cependant, la cible de l'itinéraire fourre-tout doit être la primitive de calcul.

Nous recommandons l'une des approches suivantes pour gérer votre public dossier.

Routage de secours fourre-tout

Pour les SSR frameworks tels que Nuxt.js, lorsqu'une route fourre-tout est spécifiée pour la cible primitive de calcul, les auteurs du framework peuvent envisager de spécifier une solution de secours statique pour la route fourre-tout afin de résoudre le problème de routage des dossiers. public Cependant, ce type de règle de routage interrompt les pages 404 affichées côté serveur. Par exemple, si l'utilisateur final visite une page qui n'existe pas, l'application affiche une page 404 avec un code d'état 404. Toutefois, si la route fourre-tout comporte une solution de secours statique, la page 404 n'est pas affichée. Au lieu de cela, la requête revient à la primitive statique et aboutit toujours à un code d'état 404, mais la page 404 n'est pas rendue.

{
    "path": "/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    },
    "fallback": {
        "kind": "Static"
    }
}

Routage du chemin de base

Les frameworks qui offrent la possibilité de modifier le chemin de base de l'application sont censés ajouter le chemin de base aux actifs statiques du .amplify-hosting/static répertoire. Par exemple, si le chemin de base est/folder1/folder2, la sortie de génération pour un actif statique appelé main.css sera.amplify-hosting/static/folder1/folder2/main.css.

Cela signifie que les règles de routage doivent également être mises à jour pour refléter le chemin de base. Par exemple, si le chemin de base est/folder1/folder2, la règle de routage pour les actifs statiques du public dossier sera la suivante.

{
    "path": "/folder1/folder2/*.*",
    "target": {
        "kind": "Static"
    }
}

De même, les routes côté serveur doivent également être précédées du chemin de base. Par exemple, si le chemin de base est/folder1/folder2, la règle de routage de l'/apiitinéraire ressemblera à ce qui suit.

{
    "path": "/folder1/folder2/api/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    }
}

Cependant, le chemin de base ne doit pas être ajouté à l'itinéraire fourre-tout. Par exemple, si le chemin de base est le suivant/folder1/folder2, l'itinéraire fourre-tout restera le suivant.

{
    "path": "/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    }
}

Exemples de routes Nuxt.js

Voici un exemple de deploy-manifest.json fichier pour une application Nuxt qui montre comment spécifier des règles de routage.

{
  "version": 1,
  "routes": [
    {
      "path": "/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ],
  "computeResources": [
    {
      "name": "default",
      "entrypoint": "server.js",
      "runtime": "nodejs18.x"
    }
  ],
  "framework": {
    "name": "nuxt",
    "version": "3.8.1"
  }
}

Voici un exemple de deploy-manifest.json fichier pour Nuxt qui montre comment spécifier des règles de routage, y compris des chemins de base.

{
  "version": 1,
  "routes": [
    {
      "path": "/base-path/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/base-path/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ],
  "computeResources": [
    {
      "name": "default",
      "entrypoint": "server.js",
      "runtime": "nodejs18.x"
    }
  ],
  "framework": {
    "name": "nuxt",
    "version": "3.8.1"
  }
}

Pour plus d'informations sur l'utilisation de l'routesattribut, consultezUtilisation de l'attribut routes.