Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo della specifica di distribuzione di Amplify Hosting per configurare l'output della build

La specifica di distribuzione di Amplify Hosting è una specifica basata su file system che definisce la struttura di directory che facilita le distribuzioni su Amplify Hosting. Un framework può generare questa struttura di directory prevista come output del suo comando build, consentendo al framework di sfruttare le primitive di servizio di Amplify Hosting. Amplify Hosting comprende la struttura del pacchetto di distribuzione e lo distribuisce di conseguenza.

Per una dimostrazione video che spiega come utilizzare le specifiche di distribuzione, vedi Come ospitare qualsiasi sito Web utilizzando AWS Amplify il YouTube canale Amazon Web Services.

Di seguito è riportato un esempio della struttura di cartelle prevista da Amplify per il pacchetto di distribuzione. Ad alto livello, ha una cartella denominatastatic, una cartella denominata compute e un file manifesto di distribuzione denominato. 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

Amplify: supporto SSR primitivo

La specifica di implementazione di Amplify Hosting definisce un contratto che si avvicina strettamente alle seguenti primitive.

Il .amplify-hosting/static directory

È necessario inserire nella directory tutti i file statici accessibili al pubblico che devono essere forniti dall'applicazioneURL. .amplify-hosting/static I file all'interno di questa directory vengono serviti tramite la primitiva static assets.

I file statici sono accessibili nella radice (/) dell'applicazione URL senza alcuna modifica al contenuto, al nome del file o all'estensione. Inoltre, le sottodirectory vengono mantenute nella URL struttura e vengono visualizzate prima del nome del file. Ad esempio, .amplify-hosting/static/favicon.ico verranno servite da https://myAppId.amplify-hostingapp.com/favicon.ico e .amplify-hosting/static/_nuxt/main.js verranno servite da https://myAppId.amplify-hostingapp.com/_nuxt/main.js

Se un framework supporta la possibilità di modificare il percorso di base dell'applicazione, deve anteporre il percorso di base alle risorse statiche all'interno della .amplify-hosting/static directory. Ad esempio, se il percorso di base è/folder1/folder2, l'output di build per una risorsa statica chiamata main.css sarà. .amplify-hosting/static/folder1/folder2/main.css

Il .amplify-hosting/compute directory

Una singola risorsa di calcolo è rappresentata da una singola sottodirectory denominata default contenuta all'interno della .amplify-hosting/compute directory. Il percorso è. .amplify-hosting/compute/default Questa risorsa di calcolo è mappata alla primitiva di calcolo di Amplify Hosting.

Il contenuto della default sottodirectory deve essere conforme alle seguenti regole.

Amplify Hosting raggruppa e distribuisce tutti i file all'interno della sottodirectory in una risorsa di default elaborazione fornita. A ogni risorsa di elaborazione vengono allocati 512 MB di storage temporaneo. Questo storage non è condiviso tra le istanze di esecuzione, ma è condiviso tra le chiamate successive all'interno della stessa istanza di esecuzione. Le istanze di esecuzione sono limitate a un tempo di esecuzione massimo di 15 minuti e l'unico percorso scrivibile all'interno dell'istanza di esecuzione è la directory. /tmp La dimensione compressa di ogni pacchetto di risorse di elaborazione non può superare i 220 MB. Ad esempio, la .amplify/compute/default sottodirectory non può superare i 220 MB quando è compressa.

Il .amplify-hosting/deploy-manifest.json file

Utilizzate il deploy-manifest.json file per archiviare i dettagli di configurazione e i metadati per una distribuzione. Come minimo, un deploy-manifest.json file deve includere un version attributo, l'routesattributo con un percorso generico specificato e l'frameworkattributo con i metadati del framework specificati.

La seguente definizione dell'oggetto illustra la configurazione per un manifesto di distribuzione.

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

I seguenti argomenti descrivono i dettagli e l'utilizzo di ogni attributo nel manifesto di distribuzione.

Utilizzo dell'attributo version

L'versionattributo definisce la versione della specifica di distribuzione che si sta implementando. Attualmente, l'unica versione per le specifiche di distribuzione di Amplify Hosting è la versione 1. L'JSONesempio seguente dimostra l'utilizzo dell'attributo. version

"version": 1

Utilizzo dell'attributo routes

L'routesattributo consente ai framework di sfruttare la primitiva delle regole di routing di Amplify Hosting. Le regole di routing forniscono un meccanismo per instradare i percorsi delle richieste in entrata verso una destinazione specifica nel pacchetto di distribuzione. Le regole di routing determinano solo la destinazione di una richiesta in entrata e vengono applicate dopo che la richiesta è stata trasformata dalle regole di riscrittura e reindirizzamento. Per ulteriori informazioni su come Amplify Hosting gestisce le riscritture e i reindirizzamenti, consulta. Configurazione di reindirizzamenti e riscritture per un'applicazione Amplify

Le regole di routing non riscrivono o trasformano la richiesta. Se una richiesta in entrata corrisponde al modello di percorso di una rotta, la richiesta viene indirizzata così com'è alla destinazione della rotta.

Le regole di routing specificate nell'routesarray devono essere conformi alle seguenti regole.

La seguente definizione dell'oggetto illustra la configurazione dell'Routeoggetto.

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

La tabella seguente descrive le proprietà dell'Routeoggetto.

La seguente definizione dell'oggetto illustra la configurazione dell'oggetto. Target

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

La tabella seguente descrive le proprietà dell'Targetoggetto.

La seguente definizione dell'oggetto illustra l'utilizzo dell'enumerazione. TargetKind

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

L'elenco seguente specifica i valori validi per l'enum. TargetKind

L'JSONesempio seguente dimostra l'utilizzo dell'routesattributo con più regole di routing specificate.

"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"
      }
    }
  ]

Per ulteriori informazioni sulla specificazione delle regole di routing nel manifesto di distribuzione, vedere Le migliori pratiche per la configurazione delle regole di routing

Utilizzo dell'attributo computeResources

L'computeResourcesattributo consente ai framework di fornire metadati sulle risorse di calcolo fornite. A ogni risorsa di elaborazione deve essere associata una route corrispondente.

La seguente definizione dell'oggetto illustra l'utilizzo dell'oggetto. ComputeResource

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

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

La tabella seguente descrive le proprietà dell'ComputeResourceoggetto.

Se hai una struttura di directory simile alla seguente.

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

L'computeResourceattributo JSON for the sarà simile al seguente.

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

Utilizzo dell' imageSettings attributo

L'imageSettingsattributo consente ai framework di personalizzare il comportamento della primitiva di ottimizzazione delle immagini, che fornisce l'ottimizzazione su richiesta delle immagini in fase di esecuzione.

La seguente definizione dell'oggetto dimostra l'utilizzo dell'oggetto. ImageSettings

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

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

La tabella seguente descrive le proprietà dell'ImageSettingsoggetto.

La seguente definizione dell'oggetto illustra l'utilizzo dell'RemotePatternoggetto.

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

La tabella seguente descrive le proprietà dell'RemotePatternoggetto.

L'esempio seguente dimostra l'imageSettingsattributo.

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

Utilizzo dell'attributo framework

Utilizzate l'frameworkattributo per specificare i metadati del framework.

La seguente definizione dell'oggetto illustra la configurazione dell'oggetto. FrameworkMetadata

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

La tabella seguente descrive le proprietà dell'FrameworkMetadataoggetto.

Le migliori pratiche per la configurazione delle regole di routing

Le regole di routing forniscono un meccanismo per instradare i percorsi delle richieste in entrata verso destinazioni specifiche del pacchetto di distribuzione. In un pacchetto di distribuzione, gli autori del framework possono inviare file nell'output di compilazione che vengono distribuiti a uno dei seguenti obiettivi:

Gli autori del framework forniscono anche una serie di regole di routing nel file manifest di deploy. Ogni regola dell'array viene confrontata con la richiesta in entrata in ordine di attraversamento sequenziale, finché non si verifica una corrispondenza. Quando esiste una regola di corrispondenza, la richiesta viene indirizzata alla destinazione specificata nella regola di corrispondenza. Facoltativamente, è possibile specificare un obiettivo di riserva per ogni regola. Se la destinazione originale restituisce un errore 404, la richiesta viene indirizzata alla destinazione di fallback.

Le specifiche di distribuzione richiedono che l'ultima regola nell'ordine di attraversamento sia una regola generale. Con il percorso viene specificata una regola generale. /* Se la richiesta in entrata non corrisponde a nessuna delle rotte precedenti nell'array delle regole di routing, la richiesta viene indirizzata al target della regola generale.

Per SSR framework come Nuxt.js, l'obiettivo della regola generale deve essere la primitiva di calcolo. Questo perché SSR le applicazioni hanno pagine renderizzate lato server con percorsi che non sono prevedibili in fase di compilazione. Ad esempio, se un Nuxt.js l'applicazione ha una pagina in /blog/[slug] cui [slug] è presente un parametro di percorso dinamico. L'obiettivo della regola generica è l'unico modo per indirizzare le richieste a queste pagine.

Al contrario, è possibile utilizzare schemi di percorso specifici per indirizzare percorsi noti in fase di compilazione. Ad esempio, Nuxt.js serve risorse statiche dal /_nuxt percorso. Ciò significa che il /_nuxt/* percorso può essere mirato da una regola di routing specifica che indirizza le richieste alla primitiva degli asset statici.

Routing delle cartelle pubbliche

La maggior parte dei SSR framework offre la possibilità di fornire risorse statiche mutabili da una cartella. public I file simili a favicon.ico e robots.txt sono in genere conservati all'interno della public cartella e vengono serviti dalla radice dell'applicazione. URL Ad esempio, il favicon.ico file viene fornito dahttps://example.com/favicon.ico. Nota che non esiste uno schema di percorso prevedibile per questi file. Sono quasi interamente dettati dal nome del file. L'unico modo per indirizzare i file all'interno della public cartella è utilizzare il percorso generico. Tuttavia, l'obiettivo generale della rotta deve essere la primitiva di calcolo.

Consigliamo uno dei seguenti approcci per la gestione della cartella. public

Routing fallback generico

Per SSR framework come Nuxt.js, dove viene specificata una route catch-all per la destinazione primitiva di calcolo, gli autori del framework potrebbero prendere in considerazione la possibilità di specificare un fallback statico per il percorso catch-all per risolvere il problema del routing delle cartelle. public Tuttavia, questo tipo di regola di routing interrompe le pagine 404 renderizzate sul lato server. Ad esempio, se l'utente finale visita una pagina che non esiste, l'applicazione esegue il rendering di una pagina 404 con un codice di stato 404. Tuttavia, se il percorso generico ha un fallback statico, la pagina 404 non viene renderizzata. La richiesta torna invece alla primitiva statica e finisce comunque con un codice di stato 404, ma la pagina 404 non viene renderizzata.

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

Routing del percorso di base

I framework che offrono la possibilità di modificare il percorso di base dell'applicazione dovrebbero anteporre il percorso di base agli asset statici all'interno della directory. .amplify-hosting/static Ad esempio, se il percorso di base è/folder1/folder2, lo sarà l'output della build per una risorsa statica chiamata main.css. .amplify-hosting/static/folder1/folder2/main.css

Ciò significa che anche le regole di routing devono essere aggiornate per riflettere il percorso di base. Ad esempio, se il percorso di base è/folder1/folder2, la regola di routing per le risorse statiche nella public cartella sarà simile alla seguente.

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

Analogamente, anche le route lato server devono avere il percorso di base anteposto ad esse. Ad esempio, se il percorso base è/folder1/folder2, la regola di routing per il /api percorso sarà simile alla seguente.

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

Tuttavia, il percorso base non deve essere anteposto al percorso generico. Ad esempio, se il percorso base è/folder1/folder2, il percorso generale rimarrà come segue.

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

Esempi di percorsi Nuxt.js

Di seguito è riportato un deploy-manifest.json file di esempio per un'applicazione Nuxt che dimostra come specificare le regole di routing.

{
  "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"
  }
}

Di seguito è riportato un deploy-manifest.json file di esempio per Nuxt che dimostra come specificare le regole di routing, inclusi i percorsi di 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"
  }
}

Per ulteriori informazioni sull'utilizzo dell'routesattributo, vedere. Utilizzo dell'attributo routes