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 中文文档
点击查看中文文档：
系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！
此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：https://github.com/mqyqingfeng/Blog
欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。