使用「Amplify 主機」部署規格來設定組建輸出 - AWS Amplify 託管
Amplify SSR 原始支持該.amplify-hosting/static目錄該.amplify-hosting/compute目錄.amplify-hosting/deploy-manifest.json 檔案設定路由規則的最佳作法

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用「Amplify 主機」部署規格來設定組建輸出

Amplify 主機部署規格是以檔案系統為基礎的規格，可定義目錄結構，以促進 Amplify 主機的部署。框架可以生成此預期的目錄結構作為其構建命令的輸出，從而使框架能夠利用 Amplify Hosting 的服務原語。Amplify 主機了解部署包的結構並相應地進行部署。

如需說明如何使用部署規格的影片示範，請參閱如何使 AWS Amplify用 Amazon 網路服務管 YouTube 道託管任何網站。

以下是 Amplify 預期部署服務包的資料夾結構範例。在高層級，它有一個名為的資料夾static、一個名為的資料夾compute和名為的部署資訊清單檔案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 SSR 原始支持

Amplify 主機部署規格定義了一份與下列原語密切對應的合約。

靜態資產

為框架提供託管靜態文件的能力。

運算

提供能夠在連接埠 3000 上執行 Node.js HTTP 伺服器的架構。

影像最佳化

為框架提供服務，以便在運行時優化圖像。

路由規則

為框架提供一種機制，以將傳入的請求路徑映射到特定目標。

該.amplify-hosting/static目錄

您必須將要從應用程式提供的所有可公開存取的靜態檔案放URL在目.amplify-hosting/static錄中。此目錄中的文件通過靜態資產原始提供。

靜態檔案可從應用程式的根 (/) 存取，URL而不會對其內容、檔案名稱或副檔名進行任何變更。此外，子目錄會保留在URL結構中，並顯示在檔案名稱之前。作為一個例子，.amplify-hosting/static/favicon.ico將從那裡提供服務，https://myAppId.amplify-hostingapp.com/favicon.ico並.amplify-hosting/static/_nuxt/main.js將從 https://myAppId.amplify-hostingapp.com/_nuxt/main.js

如果框架支持修改應用程序的基本路徑的能力，它必須在目錄中的靜態資產前面添加基本路徑。.amplify-hosting/static例如，如果基本路徑是/folder1/folder2，那麼調用的靜態資產的構建輸出main.css將是.amplify-hosting/static/folder1/folder2/main.css。

該.amplify-hosting/compute目錄

單一計算資源由目錄default中包含的單一子目.amplify-hosting/compute錄表示。路徑是.amplify-hosting/compute/default。該計算資源映射到 Amplify 託管的計算原始。

default子目錄的內容必須符合下列規則。

  • 檔案必須存在於default子目錄的根目錄中，才能做為計算資源的進入點。

  • 入口點檔案必須是 Node.js 模組，而且必須啟動偵聽連接埠 3000 的HTTP伺服器。

  • 您可以將其他檔案放置在default子目錄中，並從入口點檔案中的程式碼參照它們。

  • 子目錄的內容必須是獨立的。入口點模塊中的代碼無法引用子目錄之外的任何模塊。請注意，框架可以以他們想要的任何方式捆綁他們的HTTP服務器。如果可以從子目錄內使用node server.js命令 (其中server.js is是項目檔案的名稱) 啟動計算程序，則 Amplify 會將目錄結構視為符合部署規格。

Amplify 主機服務包，並將default子目錄內的所有檔案部署到佈建的計算資源。每個計算資源都會配置 512 MB 的暫時儲存空間。此儲存空間不會在執行個體之間共用，但會在相同執行執行個體內的後續叫用之間共用。執行執行個體的執行時間上限為 15 分鐘，而執行執行個體中唯一可寫入的路徑是目/tmp錄。每個計算資源服務包的壓縮大小不能超過 220 MB。例如，壓縮時.amplify/compute/default子目錄不能超過 220 MB。

.amplify-hosting/deploy-manifest.json 檔案

使用該deploy-manifest.json檔案儲存部署的規劃詳細資料和中繼資料。deploy-manifest.json檔案至少必須包含version屬性、指定全部捕捉路由的routes屬性，以及具有指定架構中繼資料的framework屬性。

下列物件定義示範部署資訊清單的組態。

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

下列主題說明部署資訊清單中每個屬性的詳細資料和用法。

使用版本屬性

version屬性會定義您所實作之部署規格的版本。目前，Amplify 主機部署規格的唯一版本是第 1 版。下面的JSON例子演示了version屬性的用法。

"version": 1

使用路由屬性

該routes屬性使框架能夠利用 Amplify 託管路由規則原始。路由規則提供一種機制，可將傳入的要求路徑路由至部署服務包中的特定目標。路由規則只會指定傳入要求的目的地，而且會在重新寫入和重新導向規則轉換要求之後套用。有關 Amplify 主機如何處理重寫和重定向的更多信息，請參閱。使用重定向

路由規則不會重寫或轉換請求。如果傳入的請求與路由的路徑模式匹配，則該請求將按原樣路由到路由的目標。

routes陣列中指定的路由規則必須符合下列規則。

  • 必須指定「捕捉全部」路線。捕獲所有路由具有匹配所有傳入請求的/*模式。

  • routes陣列最多可包含 25 個項目。

  • 您必須指定Static路線或Compute路線。

  • 如果您指定Static路由，則該.amplify-hosting/static目錄必須存在。

  • 如果您指定Compute路由，則該.amplify-hosting/compute目錄必須存在。

  • 如果您指定ImageOptimization路線，您還必須指定Compute路線。這是必要的，因為純靜態應用程式尚不支援影像最佳化。

下列物件定義示範Route物件的組態。

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

下表說明Route物件的屬性。

金錀 Type 必要 描述

路徑

字串

是

定義匹配傳入請求路徑（不包括查詢字符串）的模式。

最大路徑長度為 255 個字元。

路徑必須以正斜線開頭/。

路徑可以包含下列任何字元：[A-Z]、[a-z]、[0-9]、[_-.*$/~ "'@: +]。

對於模式比對，僅支援下列萬用字元：

  • *（匹配 0 個或更多字符）

  • 該/*模式稱為全部捕獲模式，並將匹配所有傳入的請求。

目標

目標

是

定義要將匹配請求路由到的目標的對象。

如果指定了Compute路由，則ComputeResource必須存在相應的路由。

如果指定了ImageOptimization路由，也imageSettings必須指定。

撤退

目標

否

定義要在原始目標傳回 404 錯誤時回復目標的目標的物件。

對於指定的路由，fallback種類和種類不能相同。target例如，不允許從Static到Static的後援。只有沒有主體的GET要求才支援後援。如果主體存在於請求中，它將在後備期間丟棄。

下列物件定義示範Target物件的組態。

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

下表說明Target物件的屬性。

金錀 Type 必要 描述

種

目標實物

是

enum定義目標類型的。有效值為 Static、Compute 和 ImageOptimization。

src

字串

是的 Compute

否為其他原語

字串；指定部署套裝軟體中包含原始可執行程式碼的子目錄名稱。有效且僅適用於計算原始元件。

此值必須指向部署服務包中存在的其中一個計算資源。目前，此欄位唯一支援的值為default。

cacheControl

字串

否

字串；指定要套用至回應的快取控制標頭值。僅對靜態和 ImageOptimization基元有效。

指定的值會由自訂標頭覆寫。如需「Amplify 主機」客戶標頭的詳細資訊，請參閱自訂標頭。

注意

此快取控制標頭僅適用於狀態碼設定為 200 (OK) 的成功回應。

下列物件定義示範TargetKind列舉的用法。

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

下面的列表指定TargetKind枚舉的有效值。

靜態

路由請求到靜態資產原始。

運算

將要求路由至計算原始元件。

ImageOptimization

將請求路由到圖像優化原始文件。

下列JSON範例會示範具有指定多個路由規則之routes屬性的用法。

"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性

此computeResources屬性可讓架構提供有關已佈建之計算資源的中繼資料。每個計算資源都必須具有與其相關聯的對應路由。

下列物件定義示範ComputeResource物件的用法。

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

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

下表說明ComputeResource物件的屬性。

金錀 Type 必要 描述

name

字串

是

指定計算資源的名稱。名稱必須與中子目錄的名稱相符。.amplify-hosting/compute directory

對於部署規格的第 1 版，唯一的有效值為default。

runtime

ComputeRuntime

是

定義佈建之計算資源的執行階段。

有效值為 nodejs16.x、nodejs18.x 和 nodejs20.x。

入口點

字串

是

針對指定的計算資源，指定程式碼將從中執行的起始檔案名稱。檔案必須存在於代表計算資源的子目錄內。

如果您的目錄結構如下所示。

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

for JSON computeResource 屬性看起來如下所示。

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

使用屬 imageSettings 性

該imageSettings屬性使框架能夠自定義圖像優化原始的行為，在運行時提供圖像的按需優化。

下列物件定義示範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';

下表說明ImageSettings物件的屬性。

金錀 Type 必要 描述

大小

編號 []

是

支援的影像寬度陣列。

domains

字符串 []

是

允許的外部網域陣列，可以使用影像最佳化。將陣列保留空白，只允許部署網域使用影像最佳化。

remotePatterns

RemotePattern[]

是

允許的外部模式陣列，可以使用影像最佳化。與域類似，但使用正則表達式（regex）提供了更多控制。

格式

ImageFormat[]

是

允許的輸出圖像格式的數組。

minimumCacheTTL

Number

是

最佳化影像的快取持續時間 (以秒為單位)。

dangerouslyAllowSVG

Boolean

是

允許SVG輸入圖像URLs。基於安全性考量，預設會停用此功能。

下列物件定義示範RemotePattern物件的用法。

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

下表說明RemotePattern物件的屬性。

金錀 Type 必要 描述

protocol

字串

否

允許遠端病毒碼的通訊協定。

有效值為 http 或 https。

hostname

字串

是

允許遠端病毒碼的主機名稱。

您可以指定常值或萬用字元。單一 `*` 與單一子網域相符。雙「**`」符合任意數量的子網域。Amplify 不允許僅指定 `**` 的總括萬用字元。

port

字串

否

允許遠端病毒碼的連接埠。

路徑名稱

字串

否

允許遠端病毒碼的路徑名稱。

下面的例子演示了imageSettings屬性。

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

使用框架屬性

使用framework屬性來指定框架元數據。

下列物件定義示範FrameworkMetadata物件的組態。

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

下表說明FrameworkMetadata物件的屬性。

金錀 Type 必要 描述

name

字串

是

框架的名稱。

version

字串

是

框架的版本。

它必須是有效的語意版本控制（semver）字符串。

設定路由規則的最佳作法

路由規則提供一種機制，可將傳入的要求路徑路由至部署服務包中的特定目標。在部署服務包中，框架作者可以將文件發送到部署到以下任一目標的構建輸出：

  • 靜態資產原始-文件包含在目.amplify-hosting/static錄中。

  • 計算原始 — 檔案包含在目.amplify-hosting/compute/default錄中。

架構作者也會在部署資訊清單檔案中提供一系列路由規則。陣列中的每個規則都會依序遍歷順序與傳入的要求進行比對，直到有相符項目為止。當有相符規則時，要求會路由至相符規則中指定的目標。您也可以選擇為每個規則指定後援目標。如果原始目標傳回 404 錯誤，則會將要求路由至後援目標。

部署規格要求遍歷順序中的最後一個規則必須是全部捕捉規則。擷取/*全部規則會使用路徑指定。如果傳入的要求與路由規則陣列中的任何先前路由不相符，則要求會路由至 Catch-All 規則目標。

對於像這樣的SSR框架Nuxt.js，捕獲所有規則目標必須是計算原始。這是因為SSR應用程式具有伺服器端轉譯的頁面，其中包含在建置階段無法預測的路由。例如，如果一個Nuxt.js應用程序有一個頁面，/blog/[slug]其中[slug]是一個動態路由參數。「全部捕捉」規則目標是將要求路由傳送至這些頁面的唯一方法。

相反，特定路徑模式可用於定位在構建時已知的路由。例如，從/_nuxt路徑Nuxt.js提供靜態資源。這意味著該/_nuxt/*路徑可以通過將請求路由到靜態資產原始的特定路由規則定位。

公用資料夾路由

大多數SSR框架都提供了從public文件夾中提供可變靜態資產的功能。像favicon.ico和robots.txt通常保存在文件public夾中的文件，並從應用程序的根提供URL。例如，從提供favicon.ico檔案https://example.com/favicon.ico。請注意，這些檔案沒有可預測的路徑模式。它們幾乎完全由文件名決定。目標文件public夾中的文件的唯一方法是使用 Catch-All 路由。但是，捕獲所有路由目標必須是計算原始。

我們建議您使用下列其中一種方法來管理您的public資料夾。

  1. 使用路徑模式來鎖定包含副檔名的要求路徑。例如，您可以使用指 /*.*定包含副檔名的所有要求路徑。

    請注意，這種方法可能是不可靠的。例如，如果public資料夾內有沒有副檔名的檔案，則這些檔案不會受到此規則的目標。使用這種方法需要注意的另一個問題是，應用程序可能具有名稱中帶有句點的頁面。例如，在的頁面/blog/2021/01/01/hello.world將成為/*.* 規則的目標。這並不理想，因為頁面不是靜態資產。但是，您可以向此規則添加一個後備目標，以確保當靜態基本原始存在 404 錯誤時，請求會退回到計算原始文件。

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

  2. 在建置時識別資public料夾中的檔案，並為每個檔案發出路由規則。此方法無法擴充，因為部署規格有 25 個規則的限制。

    {
    "path": "/favicon.ico",
    "target": {
        "kind": "Static"
    }
},
{
    "path": "/robots.txt",
    "target": {
        "kind": "Static"
    }
}

  3. 建議您的框架用戶將所有可變靜態資產存儲在文件夾內的子文件public夾中。

    在下面的例子中，用戶可以存儲public/assets文件夾中的所有可變靜態資產。然後，/assets/*可以使用路徑模式的路由規則來定位public/assets文件夾內的所有可變靜態資產。

    {
    "path": "/assets/*",
    "target": {
        "kind": "Static"
    }
}

  4. 指定捕捉全部路由的靜態後援。這種方法具有在下捕捉全部後備路由一節中更詳細描述的缺點。

捕捉全部後備路由

對於SSR框架Nuxt.js，例如為計算原始目標指定了 Catch-all 路由，框架作者可能會考慮為 catch-all 路由指定靜態後備來解決文件夾路由問題。public不過，這種類型的路由規則會中斷伺服器端轉譯的 404 頁面。例如，如果一般使用者造訪不存在的頁面，應用程式會呈現 404 狀態碼為 404 的網頁。但是，如果捕獲所有路由具有靜態後備，則不會呈現 404 頁面。相反，請求回落到靜態原語，並且仍然以 404 狀態碼結束，但不會呈現 404 頁面。

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

基本路徑路由

提供修改應用程式基本路徑之功能的架構預期會在目錄內的靜態資產前面加上基本路徑。.amplify-hosting/static例如，如果基本路徑是/folder1/folder2，則名為 main.css 的靜態資產的構建輸出將是.amplify-hosting/static/folder1/folder2/main.css。

這意味著還需要更新路由規則以反映基本路徑。例如，如果基本路徑為/folder1/folder2，則資public料夾中靜態資產的路由規則將如下所示。

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

同樣地，伺服器端路由也需要在前面加上基底路徑。例如，如果基本路徑是/folder1/folder2，則路由的/api路由規則將如下所示。

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

但是，基準路徑不應附加在集合全部佈線之前。例如，如果基準路徑為/folder1/folder2，則集成所有佈線將保持如下所示。

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

Nuxt.js 路由的例子

以下是 Nuxt 應用程式的範例deploy-manifest.json檔案，示範如何指定路由規則。

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

以下是 Nuxt 的範例deploy-manifest.json檔案，示範如何指定路由規則 (包括基本路徑)。

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

如需有關使用routes屬性的詳細資訊，請參閱使用路由屬性。