要部署到 [Cloudflare Workers](https://workers.cloudflare.com/) 或 [Cloudflare Pages](https://pages.cloudflare.com/)，请使用 [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/main/packages/adapter-cloudflare)。 此适配器将在您使用[`adapter-auto`](adapter-auto)时默认安装。如果您打算继续使用 Cloudflare，可以将[`adapter-auto`](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`中： ```js /// file: svelte.config.js import adapter from '@sveltejs/adapter-cloudflare'; export default { kit: { adapter: adapter({ // See below for an explanation of these options config: undefined, platformProxy: { configPath: undefined, environment: undefined, persist: undefined }, fallback: 'plaintext', routes: { include: ['/*'], exclude: [''] } }) } }; ``` ## 选项 ### 配置 路径到您的[Wrangler 配置文件](https://developers.cloudflare.com/workers/wrangler/configuration/)。如果您想使用除`wrangler.jsonc`、`wrangler.json`或`wrangler.toml`之外的 Wrangler 配置文件名，可以使用此选项指定。 ### 平台代理 偏好于模拟的 `platform.env` 本地绑定。请参阅 [getPlatformProxy](https://developers.cloudflare.com/workers/wrangler/api/#parameters-1) Wrangler API 文档以获取完整选项列表。 ### 回退 是否渲染纯文本 404.html 页面或为不匹配的资产请求渲染的 SPA 回退页面。 对于 Cloudflare Workers，默认行为是对不匹配的资产请求返回一个空体的 404 状态响应。然而，如果[`assets.not_found_handling`](https://developers.cloudflare.com/workers/static-assets/routing/#2-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 的[未找到行为](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior)获取更多信息。 ### 路线 仅适用于 Cloudflare Pages。允许您自定义由`adapter-cloudflare`生成的[`_routes.json`](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file)文件。 * `include` 定义将调用函数的路由，默认为 `['/*']` * `exclude` 定义了不会调用函数的路由 — 这是一种更快、更经济的方式来提供您的应用程序的静态资源。此数组可以包括以下特殊值： * `` 包含您的应用程序的构建工件（由 Vite 生成的文件） * `` 包含您的 `static` 目录内容 * `预渲染` 包含预渲染页面列表 * ``（默认）包含上述所有内容 您最多可以组合 100 个`include`和`exclude`规则。通常，您可以省略`routes`选项，但如果（例如）您的``路径超过该限制，您可能会发现手动创建一个包含`'/articles/*'`的`exclude`列表比自动生成的 `['/articles/foo', '/articles/bar', '/articles/baz', ...]` 更有帮助。 ## Cloudflare Workers ### 基本配置 当为 Cloudflare Workers 构建时，此适配器期望在项目根目录中找到一个[Wrangler 配置文件](https://developers.cloudflare.com/workers/configuration/sites/configuration/)。它看起来应该像这样： ```jsonc /// file: wrangler.jsonc { "name": "", "main": ".svelte-kit/cloudflare/_worker.js", "compatibility_date": "2025-01-01", "assets": { "binding": "ASSETS", "directory": ".svelte-kit/cloudflare", } } ``` ### 部署 请遵循[框架指南](https://developers.cloudflare.com/workers/frameworks/framework-guides/svelte/)开始使用 Cloudflare Workers。 ## Cloudflare Pages ### 部署 请按照[入门指南](https://developers.cloudflare.com/pages/get-started/)开始使用 Cloudflare Pages。 如果您正在使用[Git 集成](https://developers.cloudflare.com/pages/get-started/git-integration/)，您的构建设置应如下所示： * 框架预设 – SvelteKit * 构建命令 – `npm run build` 或 `vite build` * 构建输出目录 – `.svelte-kit/cloudflare` ### 进一步阅读 您可能需要参考[Cloudflare 的部署 SvelteKit 网站在 Cloudflare Pages 上的文档](https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-kit-site/)。 ### 注释 函数包含在项目根目录下的 [`/functions` 目录](https://developers.cloudflare.com/pages/functions/routing/) 中，将 *不包括* 在部署中。相反，函数应作为您的 SvelteKit 应用中的 [服务器端点](routing#server) 实现，该应用编译为一个 [单个 `_worker.js` 文件](https://developers.cloudflare.com/pages/functions/advanced-mode/)。 ## 运行时 API 对象 [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) 包含您项目的 [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/)，这些绑定包括 KV/DO 命名空间等。它通过 `platform` 属性传递给 SvelteKit，同时还包括 [`ctx`](https://developers.cloudflare.com/workers/runtime-apis/context/)、[`caches`](https://developers.cloudflare.com/workers/runtime-apis/cache/) 和 [`cf`](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties)，这意味着您可以在钩子和端点中访问它： ```js // @errors: 7031 export async function POST({ request, platform }) { const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); } ``` > \[!注意\] 应优先使用 SvelteKit 内置的 [`$env` 模块]($env-static-private) 来处理环境变量。 为了使这些类型可用于您的应用，安装 [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) 并在您的 `src/app.d.ts` 中引用它们： ```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 {}; ``` ### 本地测试 Cloudflare 特定的值在 `平台` 属性中在开发和预览模式下进行模拟。根据您的 [绑定](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) 和 [Wrangler 配置文件](https://developers.cloudflare.com/workers/wrangler/) 创建本地绑定，并在开发和预览期间用于填充 `platform.env`。使用适配器配置 [`platformProxy` 选项](#Options-platformProxy) 来更改您的绑定偏好。 测试构建时，您应使用[Wrangler](https://developers.cloudflare.com/workers/wrangler/)版本 4。构建您的网站后，如果您正在测试 Cloudflare Workers，请运行 `wrangler dev .svelte-kit/cloudflare` ；如果您正在测试 Cloudflare Pages，请运行 `wrangler pages dev .svelte-kit/cloudflare` 。 ## 标题和重定向 The [`_headers`](https://developers.cloudflare.com/pages/configuration/headers/) 和 [`_redirects`](https://developers.cloudflare.com/pages/configuration/redirects/) 文件，针对 Cloudflare，可以通过将它们放入项目根目录来用于静态资源响应（如图片）。 然而，它们对由 SvelteKit 动态渲染的响应没有影响，SvelteKit 应该返回自定义头或从 [服务器端点](routing#server) 或使用 [`handle`](hooks#Server-hooks-handle) 钩子进行重定向响应。 ## 故障排除 ### Node.js 兼容性 如果您想启用[Node.js 兼容性](https://developers.cloudflare.com/workers/runtime-apis/nodejs/)，您可以将`nodejs_compat`兼容性标志添加到您的 Wrangler 配置文件中： ```jsonc /// file: wrangler.jsonc { "compatibility_flags": ["nodejs_compat"] } ``` ### 工人大小限制 当部署您的应用程序时，由 SvelteKit 生成的服务器被打包成一个单独的文件。如果经过压缩后超过[大小限制](https://developers.cloudflare.com/workers/platform/limits/#worker-size)，Wrangler 将无法发布您的 worker。通常情况下，您不太可能达到这个限制，但一些大型库可能会导致这种情况发生。在这种情况下，您可以尝试通过仅在客户端导入这些库来减小 worker 的大小。有关更多信息，请参阅[常见问题解答](./faq#How-do-I-use-a-client-side-library-accessing-document-or-window)。 ### 访问文件系统 您不能在 Cloudflare Workers 中使用`fs`——您必须[预渲染](page-options#prerender)相关路由。 ## 迁移自 Workers 站点 Cloudflare 不再推荐使用[Workers Sites](https://developers.cloudflare.com/workers/configuration/sites/configuration/)，而是推荐使用[Workers Static Assets》。迁移时，将 `@sveltejs/adapter-cloudflare-workers` 替换为`@sveltejs/adapter-cloudflare`，并从您的 Wrangler 配置文件中删除所有`site`配置设置，然后添加`assets.directory`和`assets.binding`配置设置：](https://developers.cloudflare.com/workers/static-assets/) ### svelte.config.js ```js /// file: svelte.config.js ---import adapter from '@sveltejs/adapter-cloudflare-workers';--- +++import adapter from '@sveltejs/adapter-cloudflare';+++ export default { kit: { adapter: adapter() } }; ``` ### wrangler.toml ```toml /// file: wrangler.toml ---site.bucket = ".cloudflare/public"--- +++assets.directory = ".cloudflare/public" assets.binding = "ASSETS"+++ ``` ### wrangler.jsonc ```jsonc /// file: wrangler.jsonc { --- "site": { "bucket": ".cloudflare/public" },--- +++ "assets": { "directory": ".cloudflare/public", "binding": "ASSETS" }+++ } ```