本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Amplify 託管部署規格來設定建置輸出 Amplify Hosting 部署規格是以檔案系統為基礎的規格，可定義目錄結構，以利部署至 Amplify Hosting。架構可以產生此預期的目錄結構做為其建置命令的輸出，讓架構能夠利用 Amplify Hosting 的服務基本概念。Amplify Hosting 了解部署套件的結構，並據此進行部署。 如需說明如何使用部署規格的影片示範，請參閱 *Amazon Web Services YouTube 頻道上的如何使用 託管任何網站 AWS Amplify*。 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 目錄 單一運算資源由`.amplify-hosting/compute`目錄內`default`包含名為 的單一子目錄表示。路徑為 `.amplify-hosting/compute/default`。此運算資源會映射至 Amplify Hosting 的運算基本。 `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 託管如何處理重寫和重新導向的詳細資訊，請參閱 [設定 Amplify 應用程式的重新導向和重寫](redirects.md)。 路由規則不會重寫或轉換請求。如果傳入請求符合路由的路徑模式，請求會依原狀路由至路由的目標。 `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 | 必要 | Description | | --- | --- | --- | --- | | 路徑 | String | 是 | 定義符合傳入請求路徑的模式 （不包括 querystring)。
路徑長度上限為 255 個字元。
路徑必須以正斜線 開頭`/`。
路徑可包含下列任何字元：【A-Z】、【a-z】、【0-9】、【 \_-.\*$/\~"'@：＋】。
對於模式比對，僅支援下列萬用字元：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/amplify/latest/userguide/ssr-deployment-specification.html) | | 目標 | Target | 是 | 定義目標以將相符請求路由至其中的物件。
如果指定`Compute`路由，則對應的 `ComputeResource` 必須存在。
如果指定`ImageOptimization`路由，`imageSettings`也必須指定 。 | | 備用 | Target | 否 | 如果原始目標傳回 404 錯誤，則定義要恢復目標的物件。
指定路由的`target`種類和`fallback`種類不能相同。例如，`Static`不允許從 到 `Static`的遞迴。只有沒有內文的 GET 請求才支援備用。如果請求中存在內文，則會在後援期間將其捨棄。 | 下列物件定義示範 `Target` 物件的組態。 ``` type Target = { kind: TargetKind; src?: string; cacheControl?: string; } ``` 下表說明`Target`物件的屬性。 | 金錀 | Type | 必要 | Description | | --- | --- | --- | --- | | 類型 | Targetkind | 是 | `enum` 定義目標類型的 。有效值為 `Static`、`Compute` 和 `ImageOptimization`。 | | src | String | 是 `Compute`
否 用於其他基本概念 | 字串，指定部署套件中包含基本可執行程式碼的子目錄名稱。有效且僅對運算基本需要。
值必須指向部署套件中存在的其中一個運算資源。目前，此欄位唯一支援的值為 `default`。 | | cacheControl | String | 否 | 指定要套用至回應之快取控制標頭值的字串。僅適用於靜態和 ImageOptimization 基本概念。
指定的值會由自訂標頭覆寫。如需 Amplify 託管客戶標頭的詳細資訊，請參閱 [設定 Amplify 應用程式的自訂標頭](custom-headers.md)。 此快取控制標頭只會套用至狀態碼設為 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" } } ] ``` 如需在部署資訊清單中指定路由規則的詳細資訊，請參閱 [設定路由規則的最佳實務](#routing-best-practices) ### 使用 computeResources 屬性 `computeResources` 屬性可讓架構提供有關佈建運算資源的中繼資料。每個運算資源都必須有與其相關聯的對應路由。 下列物件定義示範 `ComputeResource` 物件的用量。 ``` type ComputeResource = { name: string; runtime: ComputeRuntime; entrypoint: string; }; type ComputeRuntime = 'nodejs20.x' | 'nodejs22.x'; ``` 下表說明`ComputeResource`物件的屬性。 | 金錀 | Type | 必要 | Description | | --- | --- | --- | --- | | name | String | 是 | 指定運算資源的名稱。名稱必須符合 內子目錄的名稱`.amplify-hosting/compute directory`。
對於部署規格的第 1 版，唯一的有效值為 `default`。 | | 執行時期 | ComputeRuntime | 是 | 定義佈建運算資源的執行時間。
有效值為 `nodejs20.x` 和 `nodejs22.x`。 | | 進入點 | String | 是 | 指定程式碼將針對指定的運算資源從中執行的起始檔案名稱。檔案必須存在於代表運算資源的子目錄中。 | 如果您有如下所示的目錄結構。 ``` .amplify-hosting |---compute | |---default | |---index.js ``` `computeResource` 屬性的 JSON 會如下所示。 ``` "computeResources": [ { "name": "default", "runtime": "nodejs20.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 | 必要 | Description | | --- | --- | --- | --- | | 大小 | Number【】 | 是 | 支援的映像寬度陣列。 | | domains | 字串 【】 | 是 | 可使用映像最佳化的允許外部網域陣列。將陣列保留空白，只允許部署網域使用映像最佳化。 | | remotePatterns | RemotePattern【】 | 是 | 可使用映像最佳化的允許外部模式陣列。與網域類似，但使用規則表達式 (regex) 提供更多控制。 | | 格式 | ImageFormat【】 | 是 | 允許輸出影像格式的陣列。 | | minimumCacheTTL | Number | 是 | 最佳化映像的快取持續時間，以秒為單位。 | | dangerouslyAllowSVG | Boolean | 是 | 允許 SVG 輸入映像 URLs。基於安全考量，預設會停用此功能。 | 下列物件定義示範 `RemotePattern` 物件的用量。 ``` type RemotePattern = { protocol?: 'https'; hostname: string; port?: string; pathname?: string; } ``` 下表說明`RemotePattern`物件的屬性。 | 金錀 | Type | 必要 | Description | | --- | --- | --- | --- | | protocol | String | 否 | 允許遠端模式的通訊協定。唯一有效的值為 `https`。 | | hostname | String | 是 | 允許遠端模式的主機名稱。
您可以指定常值或萬用字元。單一 `\*` 符合單一子網域。雙 `\*\*` 符合任意數量的子網域。Amplify 不允許只指定 `\*\*` 的空白萬用字元。 | | port | String | 否 | 允許遠端模式的連接埠。 | | 路徑名稱 | String | 否 | 允許遠端模式的路徑名稱。 | 下列範例示範 `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 | 必要 | Description | | --- | --- | --- | --- | | name | String | 是 | 架構的名稱。 | | version | String | 是 | 架構的版本。
它必須是有效的語意版本控制 （轉換器） 字串。 | ## 設定路由規則的最佳實務 路由規則提供將傳入請求路徑路由到部署套件中特定目標的機制。在部署套件中，架構作者可以將檔案發送到部署到下列任一目標的建置輸出： + **靜態資產基本 –** 檔案包含在 `.amplify-hosting/static`目錄中。 + **運算基本 –** 檔案包含在 `.amplify-hosting/compute/default`目錄中。 架構作者也會在部署資訊清單檔案中提供一系列路由規則。陣列中的每個規則都會以循序周遊順序比對傳入的請求，直到相符為止。有相符的規則時，請求會路由到相符規則中指定的目標。或者，可以為每個規則指定備用目標。如果原始目標傳回 404 錯誤，請求會路由到備用目標。 部署規格*需要*周遊順序中的最後一個規則，才能成為全部截獲規則。使用 `/*` 路徑指定全部擷取規則。如果傳入的請求與路由規則陣列中的任何先前路由不相符，則請求會路由到全部截獲規則目標。 對於 等 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`資料夾內的檔案設為目標的唯一方法是使用全部截獲路由。不過，全部擷取的路由目標必須是運算基本目標。 我們建議您使用下列其中一種方法來管理您的`public`資料夾。 1. 使用路徑模式來鎖定包含副檔名的請求路徑。例如，您可以使用 ` /*.*`以包含副檔名的所有請求路徑為目標。 請注意，這種方法可能不可靠。例如，如果`public`資料夾中有沒有副檔名的檔案，則此規則不會以這些檔案為目標。使用此方法需要注意的另一個問題是，應用程式的名稱中可能有包含句點的頁面。例如，`/*.* `規則`/blog/2021/01/01/hello.world`會將 的頁面設為目標。這並不理想，因為頁面不是靜態資產。不過，您可以將備用目標新增至此規則，以確保當靜態基本命令出現 404 錯誤時，請求會回到運算基本命令。 ``` { "path": "/*.*", "target": { "kind": "Static" }, "fallback": { "kind": "Compute", "src": "default" } } ``` 1. 在建置時間識別 `public` 資料夾中的檔案，並為每個檔案發出路由規則。此方法無法擴展，因為部署規格有 25 個規則的限制。 ``` { "path": "/favicon.ico", "target": { "kind": "Static" } }, { "path": "/robots.txt", "target": { "kind": "Static" } } ``` 1. 建議架構使用者將所有可變靜態資產存放在 `public` 資料夾內的子資料夾內。 在下列範例中，使用者可以將所有可變靜態資產存放在 `public/assets` 資料夾內。然後，具有路徑模式的路由規則`/assets/*`可用於將`public/assets`資料夾中所有可變靜態資產設為目標。 ``` { "path": "/assets/*", "target": { "kind": "Static" } } ``` 1. 指定全部擷取路由的靜態備用。此方法有缺點，會在下[全部擷取備用路由](#catchall-fallback-routing)一節中詳細說明。 ### 全部擷取備用路由 對於為運算基本目標指定全部Nuxt.js擷取路由的 SSR 架構，架構作者可能會考慮為全部擷取路由指定靜態備用，以解決`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": "nodejs22.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": "nodejs22.x" } ], "framework": { "name": "nuxt", "version": "3.8.1" } } ``` 如需使用 `routes` 屬性的詳細資訊，請參閱 [使用路由屬性](#deployment-manifest-routes)。