SvelteKit 最新中文文档教程（10）—— 部署 Cloudflare Pages 和 Cloudflare Workers

前言

Svelte，一个语法简洁、入门容易，面向未来的前端框架。

从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1：

Svelte 以其独特的编译时优化机制著称，具有轻量级、高性能、易上手等特性，非常适合构建轻量级 Web 项目。

为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。

如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。

Cloudflare Pages

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

当您使用 adapter-auto 时，此适配器将被默认安装。如果您计划继续使用 Cloudflare Pages，您可以从 adapter-auto 切换到直接使用这个适配器，这样在本地开发时可以模拟 Cloudflare Workers 特定的值，类型声明会自动应用，并且提供设置 Cloudflare 特定选项的功能。

比较

• adapter-cloudflare – 支持所有 SvelteKit 功能；为 Cloudflare Pages 构建
• adapter-cloudflare-workers – 支持所有 SvelteKit 功能；为 Cloudflare Workers 构建
• adapter-static – 仅生成客户端静态资源；兼容 Cloudflare Pages

使用方法

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

// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';export default {kit: {adapter: adapter({// 以下选项的说明请见下文routes: {include: ['/*'],exclude: ['<all>']},platformProxy: {configPath: 'wrangler.toml',environment: undefined,experimentalJsonConfig: false,persist: false}})}
};

选项

routes

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

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

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

platformProxy

模拟 platform.env 本地绑定的偏好设置。完整的选项列表请参见 getPlatformProxy Wrangler API 文档。

部署

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

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

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

运行时 API

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

// @errors: 7031
export async function POST({ request, platform }) {const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

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

要为您的绑定包含类型声明，请在您的 src/app.d.ts 中引用它们：

/// file: src/app.d.ts
import { KVNamespace, DurableObjectNamespace } from '@cloudflare/workers-types';declare global {namespace App {interface Platform {
+++			env?: {YOUR_KV_NAMESPACE: KVNamespace;YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;};+++}}
}export {};

本地测试

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

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

注意事项

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

特定于 Cloudflare Pages 的 _headers 和 _redirects 文件可以通过将它们放入 /static 文件夹来用于静态资源响应（如图片）。

然而，它们对 SvelteKit 动态渲染的响应没有影响，这些响应应该从 服务端点 或通过 handle 钩子返回自定义头部或重定向响应。

故障排除

进一步阅读

您可能想参考 Cloudflare 关于部署 SvelteKit 站点的文档。

访问文件系统

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

Cloudflare Workers

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

[!NOTE] 除非您有特别原因使用 adapter-cloudflare-workers，否则建议使用 adapter-cloudflare。两个适配器具有相同的功能，但 Cloudflare Pages 提供了更多功能，如 GitHub 集成自动构建和部署、预览部署、即时回滚等。

使用方法

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

// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare-workers';export default {kit: {adapter: adapter({config: 'wrangler.toml',platformProxy: {configPath: 'wrangler.toml',environment: undefined,experimentalJsonConfig: false,persist: false}})}
};

选项

config

自定义 wrangler.toml 或 wrangler.json 配置文件的路径。

platformProxy

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

基本配置

此适配器需要在项目根目录中找到 wrangler.toml/wrangler.json 文件。它应该看起来像这样：

/// file: wrangler.toml
name = "<your-service-name>"
account_id = "<your-account-id>"main = "./.cloudflare/worker.js"
site.bucket = "./.cloudflare/public"build.command = "npm run build"compatibility_date = "2021-11-12"
workers_dev = true

<your-service-name> 可以是任何名称。<your-account-id> 可以通过登录到您的 Cloudflare 仪表板 并从 URL 末尾获取：

https://dash.cloudflare.com/<your-account-id>

[!NOTE] 您应该将 .cloudflare 目录（或您为 main 和 site.bucket 指定的任何目录）添加到 .gitignore 中。

如果您还没有安装 wrangler 并登录，需要先执行这些操作：

npm i -g wrangler
wrangler login

然后，您可以构建并部署您的应用：

wrangler deploy

自定义配置

如果您想使用 wrangler.toml 以外的配置文件，可以使用 config 选项 指定。

如果您想启用 Node.js 兼容性，可以在 wrangler.toml 中添加 “nodejs_compat” 标志：

/// file: wrangler.toml
compatibility_flags = [ "nodejs_compat" ]

运行时 API

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

// @errors: 7031
export async function POST({ request, platform }) {const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

[!NOTE] 对于环境变量，应优先使用 SvelteKit 内置的 $env 模块。

要包含绑定的类型声明，请在您的 src/app.d.ts 中引用它们：

/// file: src/app.d.ts
import { KVNamespace, DurableObjectNamespace } from '@cloudflare/workers-types';declare global {namespace App {interface Platform {
+++			env?: {YOUR_KV_NAMESPACE: KVNamespace;YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;};+++}}
}export {};

本地测试

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

要测试构建，您应该使用 wrangler 版本 3。构建完网站后，运行 wrangler dev。

故障排除

Worker 大小限制

在部署到 workers 时，SvelteKit 生成的服务端会被打包成单个文件。如果您的 worker 在压缩后超过了 大小限制，Wrangler 将无法发布。通常您不太可能遇到这个限制，但某些大型库可能会导致这种情况。在这种情况下，您可以尝试通过仅在客户端导入这些库来减小 worker 的大小。更多信息请参见 FAQ。

访问文件系统

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

Svelte 中文文档

点击查看中文文档：

• SvelteKit Cloudflare Pages
• SvelteKit Cloudflare Workers

系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：https://github.com/mqyqingfeng/Blog

欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。