As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Como usar a especificação de implantação do Amplify Hosting para configurar a saída da compilação

A especificação de implantação do Amplify Hosting é uma especificação baseada em sistema de arquivos que define a estrutura de diretórios que facilita as implantações no Amplify Hosting. Um framework pode gerar essa estrutura esperada de diretórios como saída do seu comando de compilação, permitindo que o framework aproveite as vantagens dos serviços primitivos do Amplify Hosting. A Amplify Hosting entende a estrutura do pacote de implantação e o implanta adequadamente.

Para ver uma demonstração em vídeo que explica como usar a especificação de implantação, consulte Como hospedar qualquer AWS Amplify site usando o YouTube canal Amazon Web Services.

Veja a seguir um exemplo da estrutura de pastas que o Amplify espera para o pacote de implantação. Em um alto nível, ele tem uma pasta chamada static, uma pasta chamada compute e um arquivo de manifesto de implantação chamado 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

Amplifique SSR o suporte primitivo

A especificação de implantação do Amplify Hosting define um contrato que mapeia de perto os seguintes primitivos.

A ferramenta .amplify-hosting/static directory

Você deve colocar todos os arquivos estáticos acessíveis ao público que devem ser servidos pelo aplicativo URL no .amplify-hosting/static diretório. Os arquivos dentro desse diretório serão oferecidos por meio do primitivo de ativos estáticos.

Os arquivos estáticos podem ser acessados na raiz (/) do aplicativo URL sem nenhuma alteração em seu conteúdo, nome de arquivo ou extensão. Além disso, os subdiretórios são preservados na URL estrutura e aparecem antes do nome do arquivo. Por exemplo, .amplify-hosting/static/favicon.ico será oferecido de https://myAppId.amplify-hostingapp.com/favicon.ico, enquanto .amplify-hosting/static/_nuxt/main.js será oferecido de https://myAppId.amplify-hostingapp.com/_nuxt/main.js.

Se um framework for compatível com a capacidade de modificar o caminho base da aplicação, ele deverá prefixar o caminho base aos ativos estáticos dentro do diretório .amplify-hosting/static. Por exemplo, se o caminho base for /folder1/folder2, a saída de compilação para um ativo estático chamado main.css será .amplify-hosting/static/folder1/folder2/main.css.

A ferramenta .amplify-hosting/compute directory

Um único recurso computacional é representado por um único subdiretório chamado default contido no diretório .amplify-hosting/compute. O caminho é .amplify-hosting/compute/default. Esse recurso computacional é mapeado para o primitivo computacional do Amplify Hosting.

O conteúdo do subdiretório default deve estar em conformidade com as regras a seguir.

O Amplify Hosting agrupa e implanta todos os arquivos dentro do subdiretório default em um recurso computacional provisionado. Cada recurso computacional recebe 512 MB de armazenamento temporário. Esse armazenamento não é compartilhado entre instâncias de execução, mas é compartilhado entre invocações subsequentes na mesma instância de execução. As instâncias de execução estão limitadas a um tempo máximo de 15 minutos de execução, e o único caminho gravável dentro da instância de execução é o diretório /tmp. O tamanho compactado de cada pacote de recursos computacionais não pode ultrapassar 220 MB. Por exemplo, o subdiretório .amplify/compute/default não pode ultrapassar 220 MB quando compactado.

A ferramenta .amplify-hosting/deploy-manifest.json file

Use o arquivo deploy-manifest.json para armazenar os detalhes da configuração e os metadados de uma implantação. Um arquivo deploy-manifest.json deve incluir, no mínimo, um atributo version, o atributo routes com uma rota abrangente especificada e o atributo framework com metadados de framework especificados.

A definição de objeto a seguir demonstra a configuração de um manifesto de implantação.

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

Os tópicos a seguir descrevem os detalhes e o uso de cada atributo no manifesto de implantação.

Como usar o atributo de versão

O atributo version define a versão da especificação de implantação que você está implementando. No momento, a única versão da especificação de implantação do Amplify Hosting é a versão 1. O JSON exemplo a seguir demonstra o uso do version atributo.

"version": 1

Como usar o atributo routes

O atributo routes permite que as estruturas aproveitem o primitivo de regras de roteamento do Amplify Hosting. As regras de roteamento fornecem um mecanismo para rotear os caminhos de solicitação de entrada para um destino específico no pacote de implantação. As regras de roteamento determinam somente o destino de uma solicitação recebida e são aplicadas depois que a solicitação é transformada pelas regras de regravação e redirecionamento. Para obter mais informações sobre como o Amplify Hosting processar regravações e redirecionamentos, consulte Configuração de redirecionamentos e regravações para uma aplicação do Amplify.

As regras de roteamento não regravam nem transformam a solicitação. Se uma solicitação recebida corresponder ao padrão de caminho de uma rota, a solicitação será roteada no estado em que se encontra para o destino da rota.

As regras de roteamento especificadas na matriz routes devem obedecer às seguintes regras.

A definição de objeto a seguir demonstra a configuração para o objeto Route.

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

A tabela a seguir descreve as propriedades do objeto Route.

A definição de objeto a seguir demonstra a configuração para o objeto Target.

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

A tabela a seguir descreve as propriedades do objeto Target.

A definição de objeto a seguir demonstra o uso da enumeração TargetKind.

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

A lista a seguir especifica os valores válidos para a enumeração TargetKind.

O JSON exemplo a seguir demonstra o uso do routes atributo com várias regras de roteamento especificadas.

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

Para obter mais informações sobre como especificar regras de roteamento em seu manifesto de implantação, consulte Práticas recomendadas para a configuração de regras de roteamento.

Usando o computeResources atributo

O atributo computeResources permite que as estruturas forneçam metadados sobre os recursos computacionais provisionados. Cada recurso computacional deve ter uma rota correspondente associada.

A definição de objeto a seguir demonstra o uso do objeto ComputeResource.

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

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

A tabela a seguir descreve as propriedades do objeto ComputeResource.

Se você tiver uma estrutura de diretórios semelhante ao seguinte exemplo.

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

O JSON para o computeResource atributo terá a seguinte aparência.

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

Usando o imageSettings atributo

O atributo imageSettings permite que os frameworks personalizem o comportamento do primitivo de otimização de imagem, que fornece otimização sob demanda de imagens em runtime.

A definição de objeto a seguir demonstra o uso do objeto 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';

A tabela a seguir descreve as propriedades do objeto ImageSettings.

A definição de objeto a seguir demonstra o uso do objeto RemotePattern.

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

A tabela a seguir descreve as propriedades do objeto RemotePattern.

O exemplo a seguir demonstra o atributo imageSettings.

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

Como usar o atributo framework

Use o atributo framework para especificar os metadados do framework.

A definição de objeto a seguir demonstra a configuração para o objeto FrameworkMetadata.

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

A tabela a seguir descreve as propriedades do objeto FrameworkMetadata.

Práticas recomendadas para a configuração de regras de roteamento

As regras de roteamento fornecem um mecanismo para rotear os caminhos de solicitação de entrada para destinos específicos no pacote de implantação. Em um pacote de implantação, os criadores do framework podem emitir arquivos para a saída da compilação que são implantados em qualquer um dos seguintes destinos:

Os criadores do framework também fornecem uma matriz de regras de roteamento no arquivo de manifesto de implantação. Cada regra na matriz é comparada com a solicitação recebida em ordem de passagem sequencial, até que haja uma correspondência. Quando houver uma regra correspondente, a solicitação será roteada para o destino especificado na regra correspondente. Como opção, é possível especificar um destino de fallback para cada regra. Se o destino original retornar um erro 404, a solicitação será roteada para o destino de fallback.

A especificação de implantação exige que a última regra na ordem de passagem seja uma regra abrangente. Uma regra abrangente é especificada com o caminho /*. Se a solicitação recebida não corresponder a nenhuma das rotas anteriores na matriz de regras de roteamento, a solicitação será roteada para o destino da regra abrangente.

Para SSR estruturas como Nuxt.js, o alvo da regra abrangente deve ser a computação primitiva. Isso ocorre porque os SSR aplicativos têm páginas renderizadas do lado do servidor com rotas que não são previsíveis no momento da construção. Por exemplo, se um Nuxt.js o aplicativo tem uma página na /blog/[slug] qual [slug] está um parâmetro de rota dinâmica. O destino regra abrangente é a única maneira de rotear solicitações para essas páginas.

Por outro lado, é possível usar padrões de caminho específicos para direcionar rotas que sejam conhecidas no momento da compilação. Por exemplo, Nuxt.js serve ativos estáticos do /_nuxt caminho. Isso significa que o caminho /_nuxt/* pode ser direcionado por uma regra específica de roteamento que roteia solicitações para o primitivo de ativos estáticos.

Roteamento de pasta pública

A maioria das SSR estruturas oferece a capacidade de fornecer ativos estáticos mutáveis a partir de uma public pasta. Arquivos como favicon.ico e normalmente robots.txt são mantidos dentro da public pasta e são servidos a partir da raiz do aplicativoURL. Por exemplo, o arquivo favicon.ico é fornecido diretamente de https://example.com/favicon.ico. Observe que não há um padrão de caminho previsível para esses arquivos. Eles são quase que totalmente ditados pelo nome do arquivo. A única maneira de direcionar arquivos dentro da pasta public é usar a rota abrangente. No entanto, o destino geral da rota precisa ser o primitivo de computação.

Recomendamos uma das seguintes abordagens para gerenciar sua pasta public.

Roteamento abrangente de fallback

Para SSR estruturas como Nuxt.js, em que uma rota abrangente é especificada para o destino primitivo de computação, os autores da estrutura podem considerar a especificação de um substituto estático para a rota abrangente para resolver o problema de roteamento de pastas. public No entanto, esse tipo de regra de roteamento interrompe as páginas 404 renderizadas no lado do servidor. Por exemplo, se o usuário final visitar uma página que não exista, a aplicação vai renderizar uma página 404 com um código de status 404. No entanto, se a rota abrangente tiver um fallback estático, a página 404 não será renderizada. Em vez disso, a solicitação retornará para o primitivo estático e ainda terminará com um código de status 404, mas a página 404 não será renderizada.

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

Roteamento de caminho base

Espera-se que frameworks com a capacidade de modificar o caminho base da aplicação possam prefixar o caminho base aos ativos estáticos dentro do diretório .amplify-hosting/static. Por exemplo, se o caminho base for /folder1/folder2, a saída de compilação para um ativo estático chamado main.css será .amplify-hosting/static/folder1/folder2/main.css.

Isso significa que também é necessário atualizar as regras de roteamento para refletir o caminho base. Por exemplo, se o caminho base for /folder1/folder2, a regra de roteamento para os ativos estáticos na pasta public terá a seguinte aparência.

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

Da mesma forma, também é necessário prefixar o caminho base nas rotas do lado do servidor. Por exemplo, se o caminho base for /folder1/folder2, a regra de roteamento para a rota /api terá a seguinte aparência.

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

No entanto, o caminho base não deverá ser prefixado à rota abrangente. Por exemplo, se o caminho base for /folder1/folder2, a rota abrangente permanecerá da seguinte maneira.

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

Exemplos de rotas do Nuxt.js

Veja a seguir um exemplo de arquivo deploy-manifest.json para uma aplicação Nuxt que demonstra como especificar regras de roteamento.

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

Veja a seguir um exemplo de arquivo deploy-manifest.json para Nuxt que demonstra como especificar regras de roteamento que incluem caminhos 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"
  }
}

Para obter mais informações sobre o uso do atributo routes, consulte Como usar o atributo routes.