Cloudflare

要部署到 Cloudflare Workers 或 Cloudflare Pages，请使用 adapter-cloudflare。

此适配器将在您使用adapter-auto时默认安装。如果您打算继续使用 Cloudflare，可以将adapter-auto切换为直接使用此适配器，以便在本地开发期间模拟event.platform，自动应用类型声明，并提供设置 Cloudflare 特定选项的能力。

比较

• adapter-cloudflare – 支持所有 SvelteKit 功能；为 Cloudflare Workers 静态资源和 Cloudflare Pages 构建
• adapter-cloudflare-workers – 已弃用。支持所有 SvelteKit 功能；为 Cloudflare Workers 网站构建
• 适配器-静态 – 仅生成客户端静态资源；兼容 Cloudflare Workers 静态资源和 Cloudflare Pages

使用

安装 npm i -D @sveltejs/adapter-cloudflare 后，将适配器添加到您的svelte.config.js中：

import import adapteradapter from '@sveltejs/adapter-cloudflare';

export default {
	
kit: {
    adapter: any;
}kit: {
		adapter: anyadapter: import adapteradapter({
			// See below for an explanation of these options
			config: undefinedconfig: var undefinedundefined,
			
platformProxy: {
    configPath: undefined;
    environment: undefined;
    persist: undefined;
}platformProxy: {
				configPath: undefinedconfigPath: var undefinedundefined,
				environment: undefinedenvironment: var undefinedundefined,
				persist: undefinedpersist: var undefinedundefined
			},
			fallback: stringfallback: 'plaintext',
			
routes: {
    include: string[];
    exclude: string[];
}routes: {
				include: string[]include: ['/*'],
				exclude: string[]exclude: ['<all>']
			}
		})
	}
};

选项

配置

路径到您的Wrangler 配置文件。如果您想使用除wrangler.jsonc、wrangler.json或wrangler.toml之外的 Wrangler 配置文件名，可以使用此选项指定。

平台代理

偏好于模拟的 platform.env 本地绑定。请参阅 getPlatformProxy Wrangler API 文档以获取完整选项列表。

回退

是否渲染纯文本 404.html 页面或为不匹配的资产请求渲染的 SPA 回退页面。

对于 Cloudflare Workers，默认行为是对不匹配的资产请求返回一个空体的 404 状态响应。然而，如果assets.not_found_handling Wrangler 配置设置被设置为"404-page"，当请求失败匹配资产时，将提供此页面。如果assets.not_found_handling被设置为"single-page-application"，无论指定了什么fallback选项，适配器都将渲染 SPA 回退 index.html 页面。

对于 Cloudflare Pages，此页面仅在请求与routes.exclude中的条目不匹配且无法匹配资产时才会被提供。

大多数情况下，plaintext就足够了，但如果您使用routes.exclude手动排除一组预渲染页面且不超过 100 个路由限制，您可能希望使用spa来避免向用户显示未样式化的 404 页面。

查看 Cloudflare Pages 的未找到行为获取更多信息。

路线

仅适用于 Cloudflare Pages。允许您自定义由adapter-cloudflare生成的_routes.json文件。

• include 定义将调用函数的路由，默认为 ['/*']
• exclude 定义了不会调用函数的路由 — 这是一种更快、更经济的方式来提供您的应用程序的静态资源。此数组可以包括以下特殊值：
  • <build> 包含您的应用程序的构建工件（由 Vite 生成的文件）
  • <files> 包含您的 static 目录内容
  • 预渲染 包含预渲染页面列表
  • <all>（默认）包含上述所有内容

您最多可以组合 100 个include和exclude规则。通常，您可以省略routes选项，但如果（例如）您的<prerendered>路径超过该限制，您可能会发现手动创建一个包含'/articles/*'的exclude列表比自动生成的 ['/articles/foo', '/articles/bar', '/articles/baz', ...] 更有帮助。

Cloudflare Workers

基本配置

当为 Cloudflare Workers 构建时，此适配器期望在项目根目录中找到一个Wrangler 配置文件。它看起来应该像这样：

{
	"name": "<any-name-you-want>",
	"main": ".svelte-kit/cloudflare/_worker.js",
	"compatibility_date": "2025-01-01",
	"assets": {
		"binding": "ASSETS",
		"directory": ".svelte-kit/cloudflare",
	}
}

部署

请遵循框架指南开始使用 Cloudflare Workers。

Cloudflare Pages

部署

请按照入门指南开始使用 Cloudflare Pages。

如果您正在使用Git 集成，您的构建设置应如下所示：

• 框架预设 – SvelteKit
• 构建命令 – npm run build 或 vite build
• 构建输出目录 – .svelte-kit/cloudflare

进一步阅读

您可能需要参考Cloudflare 的部署 SvelteKit 网站在 Cloudflare Pages 上的文档。

注释

函数包含在项目根目录下的 /functions 目录 中，将 不包括 在部署中。相反，函数应作为您的 SvelteKit 应用中的 服务器端点 实现，该应用编译为一个 单个 _worker.js 文件。

运行时 API

对象 env 包含您项目的 bindings，这些绑定包括 KV/DO 命名空间等。它通过 platform 属性传递给 SvelteKit，同时还包括 ctx、caches 和 cf，这意味着您可以在钩子和端点中访问它：

export async function 
function POST({ request, platform }: {
    request: any;
    platform: any;
}): Promise<void>POST({ request, platform }) {

	const const x: anyx = platform: anyplatform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

[!注意] 应优先使用 SvelteKit 内置的 $env 模块 来处理环境变量。

为了使这些类型可用于您的应用，安装 @cloudflare/workers-types 并在您的 src/app.d.ts 中引用它们：

import { interface KVNamespace<Key extends string = string>KVNamespace, interface DurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined>DurableObjectNamespace } from '@cloudflare/workers-types';

declare global {
	namespace App {
		interface interface App.Platform
If your adapter provides platform-specific context via event.platform, you can specify it here.
Platform {
			
App.Platform.env?: {
    YOUR_KV_NAMESPACE: KVNamespace;
    YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
} | undefinedenv?: {
				type YOUR_KV_NAMESPACE: KVNamespace<string>YOUR_KV_NAMESPACE: interface KVNamespace<Key extends string = string>KVNamespace;
				type YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace<undefined>YOUR_DURABLE_OBJECT_NAMESPACE: interface DurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined>DurableObjectNamespace;
			};
		}
	}
}

export {};

本地测试

Cloudflare 特定的值在 平台 属性中在开发和预览模式下进行模拟。根据您的 绑定 和 Wrangler 配置文件 创建本地绑定，并在开发和预览期间用于填充 platform.env。使用适配器配置 platformProxy 选项 来更改您的绑定偏好。

测试构建时，您应使用Wrangler版本 4。构建您的网站后，如果您正在测试 Cloudflare Workers，请运行 wrangler dev .svelte-kit/cloudflare ；如果您正在测试 Cloudflare Pages，请运行 wrangler pages dev .svelte-kit/cloudflare 。

标题和重定向

The _headers 和 _redirects 文件，针对 Cloudflare，可以通过将它们放入项目根目录来用于静态资源响应（如图片）。

然而，它们对由 SvelteKit 动态渲染的响应没有影响，SvelteKit 应该返回自定义头或从 服务器端点 或使用 handle 钩子进行重定向响应。

故障排除

Node.js 兼容性

如果您想启用Node.js 兼容性，您可以将nodejs_compat兼容性标志添加到您的 Wrangler 配置文件中：

{
	"compatibility_flags": ["nodejs_compat"]
}

工人大小限制

当部署您的应用程序时，由 SvelteKit 生成的服务器被打包成一个单独的文件。如果经过压缩后超过大小限制，Wrangler 将无法发布您的 worker。通常情况下，您不太可能达到这个限制，但一些大型库可能会导致这种情况发生。在这种情况下，您可以尝试通过仅在客户端导入这些库来减小 worker 的大小。有关更多信息，请参阅常见问题解答。

访问文件系统

您不能在 Cloudflare Workers 中使用fs——您必须预渲染相关路由。

迁移自 Workers 站点

Cloudflare 不再推荐使用Workers Sites，而是推荐使用Workers Static Assets》。迁移时，将 @sveltejs/adapter-cloudflare-workers 替换为@sveltejs/adapter-cloudflare，并从您的 Wrangler 配置文件中删除所有site配置设置，然后添加assets.directory和assets.binding配置设置：

svelte.config.js

import adapter from '@sveltejs/adapter-cloudflare-workers';
import import adapteradapter from '@sveltejs/adapter-cloudflare';

export default {
	
kit: {
    adapter: any;
}kit: {
		adapter: anyadapter: import adapteradapter()
	}
};

wrangler.toml

site.bucket = ".cloudflare/public"
assets.directory = ".cloudflare/public"
assets.binding = "ASSETS"

wrangler.jsonc

{
	"site": {
		"bucket": ".cloudflare/public"
	},
	"assets": {
		"directory": ".cloudflare/public",
		"binding": "ASSETS"
	}
}