本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Next.js 的 Amplify 支援 Amplify 支援部署和託管使用 Next.js 建立的伺服器端轉譯 (SSR) Web 應用程式。Next.js 是使用 JavaScript 開發 SPAs 的 React 架構。您可以透過 Next.js 15 部署使用 Next.js 版本建置的應用程式，並具有影像最佳化和中介軟體等功能。 開發人員可以使用 Next.js 在單一專案中結合靜態網站產生 (SSG) 和 SSR。SSG 頁面會在建置時渲染，而 SSR 頁面會在請求時渲染。 渲染可以改善效能和搜尋引擎最佳化。由於 Next.js 會呈現伺服器上的所有頁面，因此每個頁面的 HTML 內容會在到達用戶端的瀏覽器時就緒。此內容也可以更快地載入。更快的載入時間可改善最終使用者的網站體驗，並正面影響網站的 SEO 排名。Prerendering 也透過讓搜尋引擎機器人輕鬆尋找和編目網站的 HTML 內容來改善 SEO。 Next.js 提供內建的分析支援，可測量各種效能指標，例如 Time to first byte (TTFB) 和 First contentful paint (FCP)。如需 Next.js 的詳細資訊，請參閱 Next.js 網站上的[入門](https://nextjs.org/docs/getting-started)。 ## Next.js 功能支援 Amplify 託管運算可完整管理使用 Next.js 版本 12 到 15 建置的應用程式的伺服器端轉譯 (SSR)。 如果您在 2022 年 11 月發行 Amplify 託管運算之前，已將 Next.js 應用程式部署至 Amplify，您的應用程式會使用 Amplify 先前的 SSR 供應商 Classic （僅限 Next.js 11)。Amplify 託管運算不支援使用 Next.js 第 11 版或更早版本建立的應用程式。我們強烈建議您將 Next.js 11 應用程式遷移至 Amplify 託管運算受管 SSR 供應商。 下列清單說明 Amplify 託管運算 SSR 供應商支援的特定功能。 **支援的功能** + 伺服器端轉譯頁面 (SSR) + 靜態頁面 + API 路由 + 動態路由 + 擷取所有路由 + SSG （靜態產生） + 增量靜態再生 (ISR) + 國際化 (i18n) 子路徑路由 + 國際化 (i18n) 網域路由 + 國際化 (i18n) 自動地區設定偵測 + 中介軟體 + 環境變數 + 映像最佳化 + Next.js 13 應用程式目錄 **不支援的功能** + Edge API Routes (*不支援邊緣中介軟體*) + *隨需*增量靜態再生 (ISR) + Next.js 串流 + 在靜態資產和最佳化映像上執行中介軟體 + 在回應後使用 執行程式碼 `unstable_after`（使用 Next.js 15 發行實驗功能） ### Next.js 影像 影像的最大輸出大小不得超過 4.3 MB。您可以將較大的影像檔案存放在某處，並使用 Next.js Image 元件來調整大小，並將其最佳化為 Webp 或 AVIF 格式，然後將其做為較小的大小。 請注意，Next.js 文件建議您安裝 Sharp 映像處理模組，讓映像最佳化在生產環境中正常運作。不過，Amplify 部署不需要這麼做。Amplify 會自動為您部署 Sharp。 # 將 Next.js SSR 應用程式部署至 Amplify 根據預設，Amplify 會使用 Amplify Hosting 的運算服務部署新的 SSR 應用程式，並支援 Next.js 版本 12 到 15。Amplify 託管運算可完整管理部署 SSR 應用程式所需的資源。您在 2022 年 11 月 17 日之前部署的 Amplify 帳戶中的 SSR 應用程式正在使用 Classic （僅限 Next.js 11) SSR 供應商。 我們強烈建議您使用 Classic （僅限 Next.js 11) SSR 將應用程式遷移至 Amplify 託管運算 SSR 供應商。Amplify 不會為您執行自動遷移。您必須手動遷移應用程式，然後啟動新建置以完成更新。如需說明，請參閱[將 Next.js 11 SSR 應用程式遷移至 Amplify 託管運算](update-app-nextjs-version.md)。 使用以下指示來部署新的 Next.js SSR 應用程式。 **使用 Amplify 託管運算 SSR 供應商將 SSR 應用程式部署至 Amplify** 1. 登入 AWS 管理主控台 並開啟 [Amplify 主控台](https://console.aws.amazon.com/amplify/)。 1. **在所有應用程式**頁面上，選擇**建立新應用程式**。 1. 在**開始使用 Amplify 建置**頁面上，選擇您的 Git 儲存庫提供者，然後選擇**下一步**。 1. 在**新增儲存庫分支**頁面上，執行下列動作： 1. 在**最近更新的儲存庫**清單中，選取要連線的儲存庫名稱。 1. 在**分支**清單中，選取要連線的儲存庫分支名稱。 1. 選擇**下一步**。 1. 應用程式需要 Amplify 代表您呼叫其他 服務時擔任的 IAM 服務角色。您可以允許 Amplify 託管運算自動為您建立服務角色，也可以指定您已建立的角色。 + 若要允許 Amplify 自動建立角色並將其連接至您的應用程式： 1. 選擇**建立並使用新的服務角色**。 + 若要連接您先前建立的服務角色： 1. 選擇**使用現有的服務角色**。 1. 從清單中選擇要使用的角色。 1. 選擇**下一步**。 1. 在**檢閱**頁面上，選擇**儲存並部署**。 ## Package.json 檔案設定 當您部署 Next.js 應用程式時，Amplify 會檢查`package.json`檔案中應用程式的建置指令碼，以判斷應用程式類型。 以下是 Next.js 應用程式的建置指令碼範例。建置指令碼`"next build"`表示應用程式同時支援 SSG 和 SSR 頁面。此建置指令碼也用於 Next.js 14 或更新版本的 SSG 專用應用程式。 ``` "scripts": { "dev": "next dev", "build": "next build", "start": "next start" }, ``` 以下是 Next.js 13 或更早版本的 SSG 應用程式的建置指令碼範例。組建指令碼`"next build && next export"`表示應用程式僅支援 SSG 頁面。 ``` "scripts": { "dev": "next dev", "build": "next build && next export", "start": "next start" }, ``` ## 擴增 Next.js SSR 應用程式的建置設定 檢查應用程式`package.json`的檔案後，Amplify 會檢查應用程式的建置設定。您可以在 Amplify 主控台或儲存庫根目錄中的 `amplify.yml` 檔案中儲存建置設定。如需詳細資訊，請參閱[設定 Amplify 應用程式的建置設定](build-settings.md)。 如果 Amplify 偵測到您正在部署 Next.js SSR 應用程式，但沒有`amplify.yml`檔案存在，它會為應用程式產生 buildspec，並將 `baseDirectory`設定為 `.next`。如果您要部署存在 `amplify.yml` 檔案的應用程式， 檔案中的建置設定會覆寫 主控台中的任何建置設定。因此，您必須在 檔案中手動`baseDirectory`將 設定為 `.next` 。 以下是 設定為 之應用程式的建置設定範例`baseDirectory``.next`。這表示建置成品適用於支援 SSG 和 SSR 頁面的 Next.js 應用程式。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` ## 擴增 Next.js 13 或更早版本的 SSG 應用程式的建置設定 如果 Amplify 偵測到您正在部署 Next.js 13 或更早版本的 SSG 應用程式，它會為應用程式產生建置規格，並將 `baseDirectory`設定為 `out`。如果您要部署存在 `amplify.yml` 檔案的應用程式，則必須`out`在 檔案中手動`baseDirectory`將 設定為 。`out` 目錄是 Next.js 建立的預設資料夾，用於存放匯出的靜態資產。當您設定應用程式的建置規格設定時，請變更`baseDirectory`資料夾的名稱以符合應用程式的組態。 以下是應用程式建置設定的範例，其中 `baseDirectory` 設定為 ，`out`表示建置成品適用於僅支援 SSG 頁面的 Next.js 13 或更早版本應用程式。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: out files: - '**/*' cache: paths: - node_modules/**/* ``` ## Next.js 14 或更新版本 SSG 應用程式的 Amplify 組建設定 在 Next.js 第 14 版`output: 'export'`中，`next export`命令已棄用，並在 `next.config.js` 檔案中取代為 ，以啟用靜態匯出。如果您在主控台中部署僅限 Next.js 14 SSG 的應用程式，Amplify 會為應用程式產生建置規格，並將 `baseDirectory`設定為 `.next`。如果您要部署存在 `amplify.yml` 檔案的應用程式，您必須在 `.next` 檔案中手動`baseDirectory`將 設定為 。這是 Amplify 用於支援 SSG 和 SSR 頁面之 Next.js `WEB_COMPUTE`應用程式的相同`baseDirectory`設定。 以下是將 `baseDirectory`設為 之僅限 Next.js 14 SSG 應用程式的建置設定範例。 `.next` ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` # 將 Next.js 11 SSR 應用程式遷移至 Amplify 託管運算 當您部署新的 Next.js 應用程式時，根據預設，Amplify 會使用最新支援的 Next.js 版本。目前，Amplify 託管運算 SSR 提供者支援 Next.js 第 15 版。 Amplify 主控台會偵測帳戶中在 2022 年 11 月發行 Amplify 託管運算服務之前部署的應用程式，並完整支援 Next.js 版本 12 到 15。主控台會顯示資訊橫幅，識別使用 Amplify 先前 SSR 供應商 Classic （僅限 Next.js 11) 部署的分支應用程式。我們強烈建議您將應用程式遷移至 Amplify 託管運算 SSR 供應商。 如果您要將託管的 Next.js 11 應用程式更新為 Next.js 12 或更新版本，您可能會在觸發部署時收到`"target" property is no longer supported`錯誤。在此情況下，您必須遷移至 Amplify 託管運算。 您必須同時手動遷移應用程式及其所有生產分支。應用程式不能同時包含 Classic （僅限 Next.js 11) 和 Next.js 12 或更新版本的分支。 使用下列指示將應用程式遷移至 Amplify 託管運算 SSR 供應商。 **將應用程式遷移至 Amplify 託管運算 SSR 供應商** 1. 登入 AWS 管理主控台 並開啟 [Amplify 主控台](https://console.aws.amazon.com/amplify/)。 1. 選擇您要遷移的 Next.js 應用程式。 **注意** 在 Amplify 主控台中遷移應用程式之前，您必須先更新應用程式的 package.json 檔案，以使用 Next.js 第 12 版或更新版本。 1. 在導覽窗格中，選擇**應用程式設定**，**一般**。 1. 在應用程式首頁上，如果應用程式已使用 *Classic （僅限 Next.js 11) SSR 提供者部署分支，則主控台會顯示橫幅。* ****在橫幅上，選擇**遷移**。 1. 在遷移確認視窗中，選取三個陳述式，然後選擇**遷移**。 1. Amplify 將建置並重新部署您的應用程式以完成遷移。 ## 還原 SSR 遷移 當您部署 Next.js 應用程式時，Amplify Hosting 會偵測應用程式中的設定，並設定應用程式的內部平台值。有三個有效的平台值。SSG 應用程式設定為平台值 `WEB`。使用 Next.js 第 11 版的 SSR 應用程式設定為平台值 `WEB_DYNAMIC`。Next.js 12 或更新版本的 SSR 應用程式設定為平台值 `WEB_COMPUTE`。 當您使用上一節中的指示遷移應用程式時，Amplify 會將應用程式的平台值從 變更為 `WEB_DYNAMIC` `WEB_COMPUTE`。遷移至 Amplify 託管運算完成後，您無法在主控台中還原遷移。若要還原遷移，您必須使用 AWS Command Line Interface 將應用程式的平台變更回 `WEB_DYNAMIC`。開啟終端機視窗並輸入下列命令，以您的唯一資訊更新應用程式 ID 和區域。 ``` aws amplify update-app --app-id abcd1234 --platform WEB_DYNAMIC --region us-west-2 ``` # 將 SSR 功能新增至靜態 Next.js 應用程式 您可以將 SSR 功能新增至使用 Amplify 部署的現有靜態 (SSG) Next.js 應用程式。在開始將 SSG 應用程式轉換為 SSR 的程序之前，請更新應用程式以使用 Next.js 第 12 版或更新版本，並新增 SSR 功能。然後，您將需要執行下列步驟。 1. 使用 AWS Command Line Interface 變更應用程式的平台類型。 1. 將服務角色新增至應用程式。 1. 在應用程式的建置設定中更新輸出目錄。 1. 更新應用程式`package.json`的檔案，以指出應用程式使用 SSR。 ## 更新平台 平台類型有三個有效值。SSG 應用程式設定為平台類型 `WEB`。使用 Next.js 第 11 版的 SSR 應用程式設定為平台類型 `WEB_DYNAMIC`。對於使用 Amplify 託管運算管理的 SSR 部署至 Next.js 12 或更新版本的應用程式，平台類型設定為 `WEB_COMPUTE`。 當您將應用程式部署為 SSG 應用程式時，Amplify 會將平台類型設定為 `WEB`。使用 AWS CLI 將應用程式的平台變更為 `WEB_COMPUTE`。開啟終端機視窗並輸入下列命令，使用您唯一的應用程式 ID 和區域更新紅色文字。 ``` aws amplify update-app --app-id abcd1234 --platform WEB_COMPUTE --region us-west-2 ``` ## 新增服務角色 服務角色是 Amplify 代表您呼叫其他 服務時擔任的 AWS Identity and Access Management (IAM) 角色。請依照下列步驟，將服務角色新增至已使用 Amplify 部署的 SSG 應用程式。 **新增服務角色** 1. 登入 AWS 管理主控台 並開啟 [Amplify 主控台](https://console.aws.amazon.com/amplify/)。 1. 如果您尚未在 Amplify 帳戶中建立服務角色，請參閱[新增服務角色](amplify-service-role.md)以完成此先決條件步驟。 1. 選擇您要新增服務角色的靜態 Next.js 應用程式。 1. 在導覽窗格中，選擇**應用程式設定**，**一般**。 1. 在**應用程式詳細資訊**頁面上，選擇**編輯** 1. 針對**服務角色**，選擇現有服務角色的名稱，或您在步驟 2 中建立的服務角色名稱。 1. 選擇**儲存**。 ## 更新建置設定 使用 SSR 功能重新部署應用程式之前，您必須更新應用程式的建置設定，將輸出目錄設定為 `.next`。您可以在 Amplify 主控台或儲存庫中存放的 `amplify.yml` 檔案中編輯建置設定。如需詳細資訊，請參閱 [設定 Amplify 應用程式的建置設定](build-settings.md)。 以下是 設定為 之應用程式的建置設定範例`baseDirectory``.next`。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` ## 更新 package.json 檔案 新增服務角色並更新建置設定後，請更新應用程式`package.json`的檔案。如下列範例所示，將建置指令碼設定為 ，`"next build"`表示 Next.js 應用程式同時支援 SSG 和 SSR 頁面。 ``` "scripts": { "dev": "next dev", "build": "next build", "start": "next start" }, ``` Amplify 會偵測儲存庫中`package.json`檔案的變更，並使用 SSR 功能重新部署應用程式。 # 讓伺服器端執行時間可存取環境變數 Amplify 託管支援在 Amplify 主控台的專案組態中設定環境變數，以將環境變數新增至應用程式的建置。 不過，根據預設，Next.js 伺服器元件無法存取這些環境變數。此行為旨在保護您的應用程式在建置階段期間使用的環境變數中存放的任何秘密。 若要讓 Next.js 可存取特定環境變數，您可以修改 Amplify 建置規格檔案，以在 Next.js 辨識的環境檔案中設定它們。這可讓 Amplify 在建置應用程式之前載入這些環境變數。 **重要** 強烈建議您不要在環境變數中存放任何登入資料、秘密或敏感資訊，因為任何可存取部署成品的使用者都可以讀取它們。 若要讓您的 SSR 運算函數存取 AWS 資源，建議使用 [IAM 角色](amplify-SSR-compute-role.md)。 下列建置規格範例示範如何在建置命令區段中新增環境變數。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - env | grep -e API_BASE_URL >> .env.production - env | grep -e NEXT_PUBLIC_ >> .env.production - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* - .next/cache/**/* ``` 在此範例中，建置命令區段包含兩個命令，在應用程式建置執行之前將環境變數寫入 `.env.production` 檔案。Amplify Hosting 可讓您的應用程式在應用程式接收流量時存取這些變數。 上述範例中建置命令區段的下列行示範如何從建置環境取得特定變數，並將其新增至 `.env.production` 檔案。 ``` - env | grep -e API_BASE_URL -e APP_ENV >> .env.production ``` 如果您的建置環境中存在變數，`.env.production`檔案將包含下列環境變數。 ``` API_BASE_URL=localhost APP_ENV=dev ``` 上述範例中建置命令區段的下列行示範如何將具有特定字首的環境變數新增至 `.env.production` 檔案。在此範例中，`NEXT_PUBLIC_`會新增具有 字首的所有變數。 ``` - env | grep -e NEXT_PUBLIC_ >> .env.production ``` 如果組建環境中有多個字`NEXT_PUBLIC_`首為 的變數，則`.env.production`檔案看起來會類似以下內容。 ``` NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk NEXT_PUBLIC_GRAPHQL_ENDPOINT=uowelalsmlsadf NEXT_PUBLIC_FEATURE_FLAG=true ``` ## monorepos 的 SSR 環境變數 如果您要在單一儲存庫中部署 SSR 應用程式，並想要讓 Next.js 可存取特定環境變數，則必須在`.env.production`檔案前面加上應用程式根目錄。下列範例建置規格適用於 Nx monorepo 中的 Next.js 應用程式，示範如何在建置命令區段中新增環境變數。 ``` version: 1 applications: - frontend: phases: preBuild: commands: - npm ci build: commands: - env | grep -e API_BASE_URL -e APP_ENV >> apps/app/.env.production - env | grep -e NEXT_PUBLIC_ >> apps/app/.env.production - npx nx build app artifacts: baseDirectory: dist/apps/app/.next files: - '**/*' cache: paths: - node_modules/**/* buildPath: / appRoot: apps/app ``` 上述範例中建置命令區段的下列幾行示範如何從建置環境取得特定變數，並將其新增至具有應用程式根 之單一儲存庫中應用程式的 `.env.production` 檔案`apps/app`。 ``` - env | grep -e API_BASE_URL -e APP_ENV >> apps/app/.env.production - env | grep -e NEXT_PUBLIC_ >> apps/app/.env.production ``` # 在單一儲存庫中部署 Next.js 應用程式 Amplify 支援通用 monorepos 中的應用程式，以及使用 npm 工作區、pnpm 工作區、Yarn 工作區、Nx 和 Turborepo 建立的 monorepo 中的應用程式。部署應用程式時，Amplify 會自動偵測您正在使用的 monorepo 建置架構。Amplify 會自動套用 npm 工作區、Yarn 工作區或 Nx 中應用程式的建置設定。Turborepo 和 pnpm 應用程式需要額外的組態。如需詳細資訊，請參閱[設定 monorepo 組建設定](monorepo-configuration.md)。 如需詳細的 Nx 範例，請參閱 [Next.js 應用程式與 Nx on AWS Amplify 託管](https://aws.amazon.com/blogs/mobile/share-code-between-next-js-apps-with-nx-on-aws-amplify-hosting/)部落格文章。