Skip to main content
SvelteKit构建和部署

Cloudflare 页面

要部署到 Cloudflare 页面，请使用 adapter-cloudflare。

¥To deploy to Cloudflare Pages, use adapter-cloudflare.

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

¥This adapter will be installed by default when you use adapter-auto. If you plan on staying with Cloudflare Pages, you can switch from adapter-auto to using this adapter directly so that values specific to Cloudflare Workers are emulated during local development, type declarations are automatically applied, and the ability to set Cloudflare-specific options is provided.

比较(Comparisons)

¥Comparisons

  • adapter-cloudflare - 标签已弃用为 Cloudflare 页面 构建

    ¥adapter-cloudflare – supports all SvelteKit features; builds for Cloudflare Pages

  • adapter-cloudflare-workers - 标签已弃用为 Cloudflare Workers 构建

    ¥adapter-cloudflare-workers – supports all SvelteKit features; builds for Cloudflare Workers

  • adapter-static - 仅生成客户端静态资源；与 Cloudflare Pages 兼容

    ¥adapter-static – only produces client-side static assets; compatible with Cloudflare Pages

用法(Usage)

¥Usage

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

¥Install with npm i -D @sveltejs/adapter-cloudflare, then add the adapter to your svelte.config.js:

svelte.config
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
			
routes: {
    include: string[];
    exclude: string[];
}
routes: {
				include: string[]include: ['/*'],
				exclude: string[]exclude: ['<all>']
			},
			
platformProxy: {
    configPath: undefined;
    environment: undefined;
    persist: undefined;
}
platformProxy: {
				configPath: undefinedconfigPath: var undefinedundefined,
				environment: undefinedenvironment: var undefinedundefined,
				persist: undefinedpersist: var undefinedundefined
			}
		})
	}
};

选项(Options)

¥Options

routes

允许你自定义由 adapter-cloudflare 生成的 _routes.json 文件。

¥Allows you to customise the _routes.json file generated by adapter-cloudflare.

  • include 定义将调用函数的路由，默认为 ['/*']

    ¥include defines routes that will invoke a function, and defaults to ['/*']

  • exclude 定义不会调用函数的路由 - 这是为你的应用的静态资源提供服务的更快、更便宜的方式。此数组可以包含以下特殊值：

    ¥exclude defines routes that will not invoke a function — this is a faster and cheaper way to serve your app’s static assets. This array can include the following special values:

    • <build> 包含你的应用的构建工件（由 Vite 生成的文件）

      ¥<build> contains your app’s build artifacts (the files generated by Vite)

    • <files> 包含你的 static 目录的内容

      ¥<files> contains the contents of your static directory

    • <prerendered> 包含预渲染页面列表

      ¥<prerendered> contains a list of prerendered pages

    • <all>（默认）包含以上所有内容

      ¥<all> (the default) contains all of the above

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

¥You can have up to 100 include and exclude rules combined. Generally you can omit the routes options, but if (for example) your <prerendered> paths exceed that limit, you may find it helpful to manually create an exclude list that includes '/articles/*' instead of the auto-generated ['/articles/foo', '/articles/bar', '/articles/baz', ...].

platformProxy

模拟 platform.env 本地绑定的首选项。有关完整选项列表，请参阅 getPlatformProxy Wrangler API 文档。

¥Preferences for the emulated platform.env local bindings. See the getPlatformProxy Wrangler API documentation for a full list of options.

部署(Deployment)

¥Deployment

请按照 Cloudflare 页面的 入门指南 开始。

¥Please follow the Get Started Guide for Cloudflare Pages to begin.

配置项目设置时，必须使用以下设置：

¥When configuring your project settings, you must use the following settings:

  • 框架预设 – SvelteKit

    ¥Framework preset – SvelteKit

  • 构建命令 - npm run build 或 vite build

    ¥Build command – npm run build or vite build

  • 构建输出目录 - .svelte-kit/cloudflare

    ¥Build output directory – .svelte-kit/cloudflare

运行时 API(Runtime APIs)

¥Runtime APIs

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

¥The env object contains your project’s bindings, which consist of KV/DO namespaces, etc. It is passed to SvelteKit via the platform property, along with context, caches, and cf, meaning that you can access it in hooks and endpoints:

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 模块 应该是首选。

¥[!NOTE] SvelteKit’s built-in $env module should be preferred for environment variables.

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

¥To make these types available to your app, install @cloudflare/workers-types and reference them in your src/app.d.ts:

src/app.d
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;
} | undefined
env?: {
				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 {};

本地测试(Testing Locally)

¥Testing Locally

在开发和预览模式下，会模拟 platform 属性中的 Cloudflare Workers 特定值。本地 bindings 是基于你的 Wrangler 配置文件 创建的，用于在开发和预览期间填充 platform.env。使用适配器配置 platformProxy 选项 更改绑定的首选项。

¥Cloudflare Workers specific values in the platform property are emulated during dev and preview modes. Local bindings are created based on your Wrangler configuration file and are used to populate platform.env during development and preview. Use the adapter config platformProxy option to change your preferences for the bindings.

要测试构建，你应该使用 Wrangler 版本 3。构建站点后，运行 wrangler pages dev .svelte-kit/cloudflare。

¥For testing the build, you should use Wrangler version 3. Once you have built your site, run wrangler pages dev .svelte-kit/cloudflare.

注释(Notes)

¥Notes

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

¥Functions contained in the /functions directory at the project’s root will not be included in the deployment. Instead, functions should be implemented as server endpoints in your SvelteKit app, which is compiled to a single _worker.js file.

Cloudflare Pages 特有的 _headers 和 _redirects 文件可用于静态资源响应（如图片），只需将它们放入 /static 文件夹即可。

¥The _headers and _redirects files specific to Cloudflare Pages can be used for static asset responses (like images) by putting them into the /static folder.

但是，它们不会影响 SvelteKit 动态渲染的响应，SvelteKit 应该返回自定义标头或重定向来自 服务器端点 或使用 handle 钩子的响应。

¥However, they will have no effect on responses dynamically rendered by SvelteKit, which should return custom headers or redirect responses from server endpoints or with the handle hook.

故障排除(Troubleshooting)

¥Troubleshooting

进一步阅读(Further reading)

¥Further reading

你可能希望参考 Cloudflare 用于部署 SvelteKit 站点的文档。

¥You may wish to refer to Cloudflare’s documentation for deploying a SvelteKit site.

Node.js 兼容性(Node.js compatibility)

¥Node.js compatibility

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

¥If you would like to enable Node.js compatibility, you can add the nodejs_compat compatibility flag to your Wrangler configuration file:

wrangler
{
	"compatibility_flags": ["nodejs_compat"]
}

Worker 大小限制(Worker size limits)

¥Worker size limits

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

¥When deploying your application, the server generated by SvelteKit is bundled into a single file. Wrangler will fail to publish your worker if it exceeds the size limits after minification. You’re unlikely to hit this limit usually, but some large libraries can cause this to happen. In that case, you can try to reduce the size of your worker by only importing such libraries on the client side. See the FAQ for more information.

访问文件系统(Accessing the file system)

¥Accessing the file system

你不能在 Cloudflare Workers 中使用 fs — 你必须 prerender 相关路由。

¥You can’t use fs in Cloudflare Workers — you must prerender the routes in question.

上一页 下一页
单页应用