SvelteKit建置與部署

Vercel

若要部署到 Vercel，請使用 adapter-vercel。

當您使用 adapter-auto 時，此轉接器將會預設安裝，但將其新增至您的專案可讓您指定 Vercel 特定的選項。

用法

使用 npm i -D @sveltejs/adapter-vercel 安裝，然後將轉接器新增至您的 svelte.config.js

svelte.config

import function adapter(config?: Config): Adapteradapter from '@sveltejs/adapter-vercel';

export default {
	kit: {
    adapter: Adapter;
}kit: {
		adapter: Adapteradapter: function adapter(config?: Config): Adapteradapter({
			// see below for options that can be set here
		})
	}
};

部署設定

若要控制如何將您的路由部署為 Vercel 上的函式，您可以指定部署設定，可以透過上述顯示的選項，或是在 +server.js、+page(.server).js 和 +layout(.server).js 檔案中使用 export const config。

例如，您可以將應用程式的某些部分部署為邊緣函式...

about/+page

/** @type {import('@sveltejs/adapter-vercel').Config} */
export const const config: {
    runtime: string;
}@type{import('@sveltejs/adapter-vercel').Config}config = {
	runtime: stringruntime: 'edge'
};

import type { type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config } from '@sveltejs/adapter-vercel';

export const const config: Configconfig: type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config = {
	runtime: "edge"runtime: 'edge'
};

...並將其他部分部署為無伺服器函式 (請注意，在版面配置內指定 config 會套用到所有子頁面)

admin/+layout

/** @type {import('@sveltejs/adapter-vercel').Config} */
export const const config: {
    runtime: string;
}@type{import('@sveltejs/adapter-vercel').Config}config = {
	runtime: stringruntime: 'nodejs22.x'
};

import type { type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config } from '@sveltejs/adapter-vercel';

export const const config: Configconfig: type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config = {
	ServerlessConfig.runtime?: `nodejs${number}.x` | undefinedWhether to use Edge Functions ('edge') or Serverless Functions ('nodejs18.x', 'nodejs20.x' etc).
@defaultSame as the build environmentruntime: 'nodejs22.x'
};

以下選項適用於所有函式

runtime：'edge'、'nodejs18.x'、'nodejs20.x' 或 'nodejs22.x'。預設情況下，轉接器將會選擇與您專案設定在 Vercel 儀表板上使用的 Node 版本相對應的 'nodejs<version>.x'
regions：邊緣網路區域的陣列 (無伺服器函式預設為 ["iad1"])，如果 runtime 為 edge (預設值) 則為 'all'。請注意，只有企業方案才支援無伺服器函式的多個區域
split：如果為 true，則會將路由部署為個別的函式。如果在轉接器層級將 split 設定為 true，則所有路由都將部署為個別的函式

此外，下列選項適用於邊緣函式

external：esbuild 在捆綁函式時應視為外部依賴項的陣列。這應該僅用於排除在 Node 外部無法執行的可選依賴項

下列選項適用於無伺服器函式

memory：函式可用的記憶體量。預設為 1024 Mb，且可以減少到 128 Mb 或在 Pro 或企業帳戶上以 64Mb 的增量增加到 3008 Mb
maxDuration：函式的最長執行時間。對於 Hobby 帳戶預設為 10 秒，Pro 帳戶為 15 秒，企業帳戶為 900 秒
isr：增量靜態重新產生的設定，如下所述

如果您的函式需要存取特定區域中的資料，建議將它們部署在相同區域 (或鄰近區域) 以獲得最佳效能。

圖片最佳化

您可以設定 images 設定來控制 Vercel 如何建置您的圖片。請參閱圖片設定參考以取得完整詳細資料。例如，您可以設定

svelte.config

import function adapter(config?: Config): Adapteradapter from '@sveltejs/adapter-vercel';

export default {
	kit: {
    adapter({ images: { sizes: [], 640: , 828: , 1200: , 1920: , 3840:  } }: {
        images: {
 sizes: Iterable<any>;
 640: any;
 828: any;
 1200: any;
 1920: any;
 3840: any;
        };
    }): any;
    formats: string[];
    minimumCacheTTL: number;
    domains: string[];
}kit: {
		function adapter({ images: { sizes: [], 640: , 828: , 1200: , 1920: , 3840:  } }: {
    images: {
        sizes: Iterable<any>;
        640: any;
        828: any;
        1200: any;
        1920: any;
        3840: any;
    };
}): anyadapter({
			images: {
    sizes: Iterable<any>;
    640: any;
    828: any;
    1200: any;
    1920: any;
    3840: any;
}images: {
				sizes: Iterable<any>sizes: [640, 828, 1200, 1920, 3840],






				formats: string[]formats: ['image/avif', 'image/webp'],
				minimumCacheTTL: numberminimumCacheTTL: 300,
				domains: string[]domains: ['example-app.vercel.app'],
			}
		})
	}
};

增量靜態重新產生

Vercel 支援增量靜態重新產生 (ISR)，它提供了預先算繪內容的效能和成本優勢，以及動態算繪內容的彈性。

若要將 ISR 新增至路由，請在您的 config 物件中包含 isr 屬性

import { import BYPASS_TOKENBYPASS_TOKEN } from '$env/static/private';

export const const config: {
    isr: {
        expiration: number;
        bypassToken: any;
        allowQuery: string[];
    };
}config = {
	isr: {
    expiration: number;
    bypassToken: any;
    allowQuery: string[];
}isr: {
		// Expiration time (in seconds) before the cached asset will be re-generated by invoking the Serverless Function.
		// Setting the value to `false` means it will never expire.
		expiration: numberexpiration: 60,

		// Random token that can be provided in the URL to bypass the cached version of the asset, by requesting the asset
		// with a __prerender_bypass=<token> cookie.
		//
		// Making a `GET` or `HEAD` request with `x-prerender-revalidate: <token>` will force the asset to be re-validated.
		bypassToken: anybypassToken: import BYPASS_TOKENBYPASS_TOKEN,

		// List of valid query parameters. Other parameters (such as utm tracking codes) will be ignored,
		// ensuring that they do not result in content being regenerated unnecessarily
		allowQuery: string[]allowQuery: ['search']
	}
};

expiration 屬性是必要的；其他所有屬性都是可選的。

預先算繪的頁面將會忽略 ISR 設定。

環境變數

Vercel 提供一組部署特定的環境變數。與其他環境變數一樣，這些變數可以從 $env/static/private 和 $env/dynamic/private (有時 — 稍後會詳細說明) 存取，且無法從其公開對應項目存取。若要從用戶端存取其中一個變數

+layout.server

import { import VERCEL_COMMIT_REFVERCEL_COMMIT_REF } from '$env/static/private';

/** @type {import('./$types').LayoutServerLoad} */
export function function load(): {
    deploymentGitBranch: any;
}@type{import('./$types').LayoutServerLoad}load() {
	return {
		deploymentGitBranch: anydeploymentGitBranch: import VERCEL_COMMIT_REFVERCEL_COMMIT_REF
	};
}

import { import VERCEL_COMMIT_REFVERCEL_COMMIT_REF } from '$env/static/private';
import type { type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>
type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>LayoutServerLoad } from './$types';

export const const load: LayoutServerLoadload: type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>
type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>LayoutServerLoad = () => {
	return {
		deploymentGitBranch: anydeploymentGitBranch: import VERCEL_COMMIT_REFVERCEL_COMMIT_REF
	};
};

+layout

<script>
	/** @type {{ data: import('./$types').LayoutServerData }} */
	let { data } = $props();
</script>

<p>This staging environment was deployed from {data.deploymentGitBranch}.</p>

<script lang="ts">
	import type { LayoutServerData } from './$types';

	let { data }: { data: LayoutServerData } = $props();
</script>

<p>This staging environment was deployed from {data.deploymentGitBranch}.</p>

由於在 Vercel 上建置時，所有這些變數在建置時間和執行時間之間都未變更，因此我們建議使用 $env/static/private — 它將會靜態取代變數，啟用死碼消除等最佳化 — 而不是 $env/dynamic/private。

偏移保護

當部署應用程式的新版本時，可能無法再存取屬於先前版本的資源。如果使用者在發生這種情況時正在使用您的應用程式，則在他們瀏覽時可能會導致錯誤 — 這稱為版本偏移。SvelteKit 會透過偵測版本偏移造成的錯誤，並導致硬式重新載入來取得應用程式的最新版本來緩解此問題，但這將導致任何用戶端狀態遺失。(您也可以透過觀察 updated 儲存值來主動緩解此問題，該值會告知用戶端何時已部署新版本。)

偏移保護是 Vercel 的一項功能，可將用戶端要求路由至其原始部署。當使用者造訪您的應用程式時，會使用部署 ID 設定 Cookie，並且只要偏移保護處於活動狀態，任何後續的要求都將路由至該部署。當他們重新載入頁面時，他們將會取得最新的部署。(updated 儲存不受此行為的限制，因此將繼續報告新的部署。) 若要啟用此功能，請造訪 Vercel 上專案設定的「進階」區段。

基於 Cookie 的偏移保護有一個警告：如果使用者在多個索引標籤中開啟應用程式的多個版本，則較舊版本的要求將會路由至較新版本，這表示它們將會回退到 SvelteKit 的內建偏移保護。

注意事項

Vercel 函式

如果您在專案根目錄的 api 目錄中包含 Vercel 函式，則 SvelteKit 將不會處理任何 /api/* 的要求。您應該在 SvelteKit 應用程式中將這些實作為API 路由，除非您需要使用非 JavaScript 語言，在這種情況下，您需要確保您的 SvelteKit 應用程式中沒有任何 /api/* 路由。

Node 版本

在特定日期之前建立的專案，預設使用的 Node 版本可能比 SvelteKit 目前要求的版本舊。您可以在專案設定中變更 Node 版本。

疑難排解

存取檔案系統

您無法在邊緣函式中使用 fs。

您可以在無伺服器函式中使用它，但它不會如預期運作，因為檔案不會從您的專案複製到您的部署中。請改用 $app/server 中的 read 函式來存取您的檔案。read 不適用於部署為邊緣函式的路由 (這在未來可能會變更)。

或者，您可以預先算繪有問題的路由。

在 GitHub 上編輯此頁面

上一步下一步

Netlify 撰寫轉接器