SvelteKitBuild and deploy

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'
};

以下选项适用于所有功能：

运行时：'edge'，'nodejs18.x'，'nodejs20.x' 或 'nodejs22.x'。默认情况下，适配器将选择与您在 Vercel 控制台配置的项目使用的 Node 版本相对应的 'nodejs<version>.x'。
regions：一个包含边缘网络区域的数组（对于无服务器函数默认为["iad1"]）或当runtime为edge（其默认值）时为'all'。请注意，对于无服务器函数，仅在企业计划中支持多个区域。
split：如果true，则将路由部署为单个函数。如果split在适配器级别设置为true，则所有路由都将部署为单个函数

此外，以下选项适用于边缘函数：

外部：esbuild 在打包函数时应将其视为外部的依赖数组。这仅应用于排除不会在 Node 外部运行的可选依赖项。

以下选项适用于无服务器函数：

内存：函数可用的内存量。默认为1024 Mb，可降低至128 Mb 或增加，以 64Mb 的增量增加，最高可达3008 Mb（在 Pro 或企业账户上）。
maxDuration：最大执行时间的函数。默认为 Hobby 账户10秒，Pro 账户15秒，企业账户900秒。
isr：配置增量静态再生，如下所述

如果您的函数需要访问特定区域的数据，建议将它们部署在同一区域（或附近）以获得最佳性能。

图片优化

您可以将图片配置设置为控制 Vercel 如何构建您的图片。请参阅图片配置参考以获取完整详情。例如，您可以设置：

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({
			images?: ImagesConfig | undefinedhttps://vercel.com/docs/build-output-api/v3/configuration#images
images: {
				sizes: number[]sizes: [640, 828, 1200, 1920, 3840],
				formats?: ImageFormat[] | undefinedformats: ['image/avif', 'image/webp'],
				minimumCacheTTL?: number | undefinedminimumCacheTTL: 300,
				domains: string[]domains: ['example-app.vercel.app'],
			}
		})
	}
};

增量静态再生

Vercel 支持增量静态重生成 (ISR)，它提供了预渲染内容的性能和成本优势，同时具有动态渲染内容的灵活性。

仅在使用 ISR 的路由上应用 ISR，在这些路由上每个访客都应该看到相同的内容（就像在预渲染时一样）。如果发生任何特定于用户的情况（如会话 cookie），它们应该在客户端通过 JavaScript 仅发生，以避免在访问之间泄露敏感信息

要向路由添加 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: numberexpiration: 60,
		bypassToken: anybypassToken: import BYPASS_TOKENBYPASS_TOKEN,
		allowQuery: string[]allowQuery: ['search']
	}
};

使用 ISR 在具有export const prerender = true的路由上不会有任何效果，因为该路由在构建时已预渲染

The expiration 属性是必需的；其他所有属性都是可选的。这些属性将在下面更详细地讨论。

到期

过期时间（以秒为单位）在通过调用无服务器函数重新生成缓存资源之前。将值设置为false表示它永远不会过期。在这种情况下，您可能希望定义一个绕过令牌以按需重新生成。

绕过令牌

一个随机令牌，可以提供在 URL 中以请求带有__prerender_bypass=<token> cookie 的资产来绕过资产的缓存版本。

制作一个 GET 或 HEAD 请求与 x-prerender-revalidate: <token> 将强制资产重新验证。

请注意，BYPASS_TOKEN字符串必须至少 32 个字符长。您可以使用 JavaScript 控制台生成一个，如下所示：

var crypto: CryptoMDN Reference
crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`Available only in secure contexts.
MDN Reference
randomUUID();

将此字符串设置为 Vercel 上的环境变量，通过登录并进入您的项目然后设置 > 环境变量。在“键”中输入BYPASS_TOKEN，在“值”中使用上面生成的字符串，然后点击“保存”。

要使此密钥在本地开发中为人所知，您可以使用 Vercel CLI，通过在本地运行vercel env pull命令来实现，如下所示：

vercel env pull .env.development.local

允许查询

有效查询参数列表，这些参数有助于生成缓存键。其他参数（如 utm 跟踪代码）将被忽略，确保它们不会导致内容不必要地重新生成。默认情况下，查询参数将被忽略。

页面中预渲染的页面将忽略 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 {import('./$types').LayoutProps} */
	let { data } = $props();
</script>

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

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

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

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

由于所有这些变量在 Vercel 构建时和运行时都没有变化，我们建议使用$env/static/private——这将静态替换变量，启用诸如死代码消除等优化——而不是使用$env/dynamic/private。

倾斜保护

当您的应用部署新版本时，旧版本的资产可能不再可访问。如果用户在此期间正在使用您的应用，导航时可能会出现错误——这被称为版本偏差。SvelteKit 通过检测由版本偏差引起的错误并强制重新加载以获取最新版本的应用来减轻这一问题，但这将导致任何客户端状态丢失。（您也可以通过观察来自$app/state的[updated.current]($app-state#updated)来主动减轻这一问题，它告诉客户端何时部署了新版本。）

偏斜保护是 Vercel 的一项功能，它将客户端请求路由到其原始部署。当用户访问您的应用时，会设置一个包含部署 ID 的 cookie，并且只要偏斜保护处于活动状态，任何后续请求都将路由到该部署。当他们重新加载页面时，他们将获得最新的部署。（updated.current不受此行为影响，将继续报告新部署。）要启用它，请访问 Vercel 项目设置的“高级”部分。

基于 Cookie 的偏斜保护有一个注意事项：如果用户在多个标签页中打开了您的应用的不同版本，旧版本的请求将被路由到新版本，这意味着它们将回退到 SvelteKit 的内置偏斜保护。

注释

Vercel 函数

如果您在项目根目录的 api 目录中包含 Vercel 函数，则对 /api/* 的任何请求将不会被 SvelteKit 处理。您应该在您的 SvelteKit 应用中实现这些作为 API 路由，除非您需要使用非 JavaScript 语言，在这种情况下，您需要确保您的 SvelteKit 应用中没有任何 /api/* 路由。

节点版本

项目在某个日期之前创建的可能会默认使用比 SvelteKit 当前要求的旧版 Node 版本。您可以在项目设置中更改 Node 版本。

故障排除

访问文件系统

您不能在边缘函数中使用fs。

您可以使用它来在无服务器函数中，但由于文件没有从您的项目复制到您的部署中，它可能不会按预期工作。相反，请使用来自 $app/server 的 read 函数来访问您的文件。read 在作为边缘函数部署的路由中不起作用（这可能在将来改变）。

或者，您也可以预渲染相关的路由。

Edit this page on GitHub llms.txt

previous next

Netlify Writing adapters