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({
			// 可以在此处设置选项，详见下文
		})
	}
};

部署配置

要控制您的路由如何作为函数部署到 Vercel，您可以通过上面显示的选项或在 +server.js、+page(.server).js 和 +layout(.server).js 文件中使用 export const config 来指定部署配置。

例如，您可以将应用的某些部分部署为 Edge Functions...

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

...其他部分则作为 Serverless Functions（注意，在布局中指定 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：边缘网络区域数组（对于 serverless 函数默认为 ["iad1"]）或当 runtime 为 edge 时为 'all'（其默认值）。注意，serverless 函数的多区域部署仅在企业版计划中支持
split：如果为 true，会导致路由被部署为独立函数。如果在适配器级别将 split 设置为 true，所有路由都将被部署为独立函数

此外，以下选项适用于 edge functions：

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

以下选项适用于 serverless 函数：

memory：函数可用的内存量。默认为 1024 Mb，可以降低到 128 Mb 或在专业版或企业版账户中以 64Mb 为增量增加到 3008 Mb
maxDuration：函数的最大执行时长。Hobby 账户默认为 10 秒，Pro 为 15 秒，Enterprise 为 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: {
		// 缓存资源将通过调用 Serverless 函数重新生成的过期时间（以秒为单位）。
		// 将值设置为 `false` 表示永不过期。
		expiration: numberexpiration: 60,

		// 可以在 URL 中提供的随机令牌，通过使用 __prerender_bypass=<token> cookie 请求资源来绕过缓存版本。
		//
		// 使用 `x-prerender-revalidate: <token>` 进行 `GET` 或 `HEAD` 请求将强制重新验证资源。
		bypassToken: anybypassToken: import BYPASS_TOKENBYPASS_TOKEN,

		// 有效查询参数列表。其他参数（如 utm 跟踪代码）将被忽略，
		// 确保它们不会导致不必要的内容重新生成
		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>此暂存环境是从 {data.deploymentGitBranch} 部署的。</p>

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

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

<p>此暂存环境是从 {data.deploymentGitBranch} 部署的。</p>

由于在 Vercel 上构建时，所有这些变量在构建时和运行时之间都保持不变，我们建议使用 $env/static/private（它会静态替换变量，启用死代码消除等优化）而不是 $env/dynamic/private。

版本偏差保护

当部署应用的新版本时，之前版本的资源可能不再可访问。如果用户在此时正在使用您的应用，在导航时可能会导致错误 — 这就是所谓的版本偏差。SvelteKit 通过检测由版本偏差导致的错误并触发硬重载来获取应用的最新版本来缓解这个问题，但这会导致客户端状态丢失。（您也可以通过观察 updated store 值来主动缓解它，这个值会告诉客户端何时部署了新版本。）

版本偏差保护是Vercel 的一个功能，可以将客户端请求路由到它们的原始部署。当用户访问您的应用时，会设置一个带有部署 ID 的 cookie，只要版本偏差保护处于活动状态，任何后续请求都会被路由到该部署。当他们重新加载页面时，将获得最新的部署。（updated store 不受此行为影响，因此将继续报告新的部署。）要启用它，请访问 Vercel 上项目设置的高级部分。

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

注意事项

Vercel 函数

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

Node 版本

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

故障排除

访问文件系统

您不能在 edge functions 中使用 fs。

您可以在 serverless 函数中使用它，但它不会按预期工作，因为文件不会从您的项目复制到您的部署中。相反，使用 $app/server 中的 read 函数来访问您的文件。read 在部署为 edge functions 的路由中不起作用（这在将来可能会改变）。

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

在 GitHub 编辑此页面

Netlify 编写适配器