SvelteKit 部署到 Cloudflare Workers：adapter-cloudflare-workers 适配器完整使用指南与迁移路径

• Web框架
• 后端
• 前端

本指南围绕 SvelteKit 官方仓库中针对 Cloudflare Workers（Workers Sites 模式）的适配器文档展开，系统讲解@sveltejs/adapter-cloudflare-workers的安装配置、Wrangler 配置文件编写、运行时platformAPI 的使用、本地测试方法与常见故障排查，并结合当前仓库中adapter-cloudflare的源码实现，剖析本地模拟cloudflare:workers环境的底层原理，最后给出从 Workers Sites 迁移到 Static Assets 的完整路径。

一、适配器概览：定位与弃用状态

adapter-cloudflare-workers是 SvelteKit 用于将应用部署到 Cloudflare Workers 的官方适配器，采用 CloudflareWorkers Sites模式（即通过site.bucket配置将静态资源上传到 KV，再由 Worker 统一处理请求）。

需要特别注意的是，该适配器已被官方弃用（deprecated）：文档明确推荐改用adapter-cloudflare，配合 Cloudflare 的 Static Assets 能力部署到 Cloudflare Workers，原因是 Cloudflare 官方计划废弃 Workers Sites。尽管如此，理解该适配器的使用方式仍具有现实意义——大量存量项目仍在使用它，且其核心概念（Wrangler 配置、platformAPI、本地模拟机制）与新适配器一脉相承，掌握它可以平滑完成迁移。

从当前仓库源码结构看，packages/目录下已不再包含adapter-cloudflare-workers包，其功能由 packages/adapter-cloudflare 完整承接。官方文档对三个相关适配器的定位对比如下（见 60-adapter-cloudflare.md）：

• adapter-cloudflare：支持全部 SvelteKit 特性；面向 Cloudflare Workers Static Assets 与 Cloudflare Pages 构建；
• adapter-cloudflare-workers：已弃用；支持全部 SvelteKit 特性；面向 Cloudflare Workers Sites 构建；
• adapter-static：仅产出客户端静态资源；兼容 Cloudflare Workers Static Assets 与 Cloudflare Pages。

二、安装与接入 vite.config.js

在项目中使用该适配器，首先安装依赖，然后在 Vite 配置中声明适配器：

npm i -D @sveltejs/adapter-cloudflare-workers

修改vite.config.js：

// @errors: 2307 /// file: vite.config.js import { sveltekit } from '@sveltejs/kit/vite'; import { defineConfig } from 'vite'; import adapter from '@sveltejs/adapter-cloudflare-workers'; export default defineConfig({ plugins: [ sveltekit({ adapter: adapter({ // see below for options that can be set here }) }) ] });

安装完成后，执行npm run build时适配器会在构建阶段执行adapt逻辑：调用 SvelteKit 的 builder 生成服务端实例、客户端资源与预渲染页面，并按 Wrangler 配置输出到指定目录。以新适配器 packages/adapter-cloudflare/index.js 的实现为参照，可以直观看到这一构建流程：读取 Wrangler 配置 → 清空目标目录 → 写入客户端资源与预渲染页面（builder.writeClient/builder.writePrerendered）→ 生成服务端实例并拷贝 Worker 模板（builder.copy将SERVER、ASSETS_BINDING等占位符替换为实际路径）→ 生成_headers/_redirects文件。旧适配器的工作方式与此同构，只是静态资源通过site.bucket交给 Wrangler 处理。

三、适配器选项（Options）

该适配器暴露两个配置项：

config

指向你的 Wrangler 配置文件 的路径。Wrangler 默认会按wrangler.jsonc、wrangler.json、wrangler.toml的顺序查找配置文件；如果你的配置文件使用了其他文件名，就必须通过该选项显式指定。

从源码实现看，这一选项最终被透传给 Wrangler 的unstable_readConfig({ config: config_file })（见 packages/adapter-cloudflare/index.js），适配器会据此读取main、assets.directory、assets.binding等字段决定 Worker 入口与资源输出目录。

platformProxy

针对本地开发/预览模式下模拟的platform.env本地绑定（bindings）的偏好设置，完整选项清单可查阅 Wrangler 的getPlatformProxyAPI 文档。常见的子项包括：

• configPath：指定读取绑定的 Wrangler 配置文件路径；
• environment：选择 Wrangler 配置中的环境（environment）；
• persist：控制本地 KV、Durable Object 等绑定状态是否持久化。

在vite.config.js中大致按如下方式使用：

adapter: adapter({ platformProxy: { configPath: 'wrangler.toml', environment: undefined, persist: true } })

四、基础配置：编写 wrangler.jsonc

该适配器期望在项目根目录找到一个 Wrangler 配置文件，内容大致如下：

/// file: wrangler.jsonc { "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" }

各字段说明：

获取 account_id

<your-account-id>可以通过两种方式获得：

1. 使用 Wrangler CLI 运行wrangler whoami；
2. 登录 Cloudflare 控制台，从浏览器地址栏 URL 的/home之前的一段路径中直接获取（即https://dash.cloudflare.com/<your-account-id>/home中的中间段）。

.gitignore 建议

[!NOTE] 应当把.cloudflare目录（以及你在main和site.bucket中指定的其他目录）和.wrangler目录加入.gitignore，避免把构建产物与本地模拟数据提交进版本库。

安装 Wrangler 并登录

npm i -D wrangler wrangler login

构建并部署

wrangler deploy

wrangler deploy会先按build.command触发npm run build，由 SvelteKit 适配器产出 Worker 脚本与静态资源，再由 Wrangler 完成上传与发布。

五、运行时 API：通过 platform 访问 Cloudflare 绑定

在 Workers 运行时环境中，env对象包含了项目的全部 bindings（KV 命名空间、Durable Object 命名空间等）。adapter-cloudflare-workers通过 SvelteKit 的platform属性把这些运行时能力注入应用，具体包括：

• env：项目的 bindings；
• ctx：执行上下文（如waitUntil）；
• caches：缓存 API；
• cf：请求携带的 Cloudflare 属性（如地理位置、TLS 信息等）。

因此在 hooks 与服务端 endpoint 中可以直接访问它们。下面是在+server.js中使用 Durable Object 的示例：

// @filename: ambient.d.ts import { DurableObjectNamespace } from '@cloudflare/workers-types'; declare global { namespace App { interface Platform { env: { YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace; }; } } } // @filename: +server.js // ---cut--- // @errors: 2355 2322 /// file: +server.js /** @type {import('./$types').RequestHandler} */ export async function POST({ request, platform }) { const x = platform?.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); }

[!NOTE] 环境变量应优先使用 SvelteKit 内置的$app/env/*模块，而不是直接从platform.env读取，这样可以在不依赖部署平台的情况下统一管理配置。

为 App.Platform 补齐类型

为了让上述类型在你的应用中可用，需要安装@cloudflare/workers-types，并在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 {};

注意这里env被声明为可选（env?），因为开发/预览模式下模拟的值在类型层面并不保证存在，访问时也应使用platform?.env这类空值安全写法。

从源码看 platform 的传递与模拟

虽然旧适配器已不在当前仓库中，但其继任者 packages/adapter-cloudflare 完整保留了这套运行时接入逻辑，可以作为理解底层机制的窗口：

• 构建产物中的 Worker 模板 files/worker.js 展示了运行时全貌：从cloudflare:workers模块导入env，用server.init({ env, read })初始化 SvelteKit 服务端，静态资源与预渲染页面通过env.ASSETS_BINDING.fetch(req)直接交给 Cloudflare 的静态资源服务，动态页面则委托给server.respond(req, { getClientAddress() })——其中客户端 IP 取自cf-connecting-ip请求头；
• 在本地 dev / preview 模式下，index.js 中的virtual_workers_module插件会在configureServer/configurePreviewServer阶段调用 Wrangler 的getPlatformProxy()，把模拟出的env、caches、cf等存到globalThis.__sveltekit_cloudflare_platform上，并让cloudflare:workers模块解析到本地桩模块；
• 桩模块 src/virtual-cloudflare-workers.js 使用AsyncLocalStorage实现env代理与withEnv，同时为tracing、waitUntil、cache提供了本地空实现；若在可预渲染路由中访问cloudflare:workers，会抛出 "Cannot access cloudflare:workers in a prerenderable route" 错误。

对于旧的adapter-cloudflare-workers，上述能力通过 SvelteKit 的platform属性（而非cloudflare:workers模块）注入，这正是两个适配器在 API 层面最显著的区别：旧适配器读platform.env，新适配器读cloudflare:workers的env导出。

六、本地测试：dev / preview 与 wrangler dev

开发与预览模式下的模拟

platform中 Cloudflare Workers 特有的值在dev 与 preview 模式下会被模拟。本地 bindings 基于你的 Wrangler 配置文件创建，并用于在开发/预览期间填充platform.env。可以通过适配器配置中的platformProxy选项调整这些绑定的行为偏好（如持久化设置、环境选择等）。

构建产物的测试

测试构建产物时，应使用 Wrangler版本 4。完成npm run build之后，运行：

wrangler dev

Wrangler 会按配置启动本地 Worker，结合site.bucket中的静态资源完整模拟生产环境的请求处理链路。

七、故障排查（Troubleshooting）

Node.js 兼容性

如果你的应用依赖 Node.js 内置模块（如node:buffer、node:stream等），需要在 Wrangler 配置文件中添加nodejs_compat兼容性标志：

/// file: wrangler.jsonc { "compatibility_flags": ["nodejs_compat"] }

该标志让 Worker 运行时提供 Node.js API 的兼容实现，从而允许部分 Node 生态依赖在 Workers 中运行。需要注意，nodejs_compat与compatibility_date的取值有对应关系，请按 Cloudflare 官方要求设置合适的日期。

Worker 大小限制

部署时，SvelteKit 生成的服务端会被打包进单个文件。如果压缩（minification）后的体积超过 Cloudflare Worker 的大小限制。

无法访问文件系统

Cloudflare Workers 运行在无盘环境中，不能使用fs模块。如果某个路由需要读取文件内容，应当：

• 将涉及文件读取的路由配置为 预渲染（prerender）（页面选项export const prerender = true;），在构建期就把内容生成到静态资源中；或
• 改用$app/server提供的read函数，它通过在部署的公开资源位置执行 fetch 来读取文件（新适配器 files/worker.js 中的read实现即通过env.ASSETS_BINDING.fetch(url)拉取资源并返回响应体）。

八、从 Workers Sites 迁移到 Static Assets

由于 Cloudflare 官方已不再推荐使用 Workers Sites（见 60-adapter-cloudflare.md 中的迁移章节），存量项目应按如下步骤迁移到adapter-cloudflare+ Workers Static Assets：

1. 替换适配器依赖与配置

npm i -D @sveltejs/adapter-cloudflare

// @errors: 2307 /// file: vite.config.js import adapter from '@sveltejs/adapter-cloudflare'; import { sveltekit } from '@sveltejs/kit/vite'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [ sveltekit({ adapter: adapter() }) ] });

2. 修改 Wrangler 配置

把site配置替换为assets.directory与assets.binding。

wrangler.toml形式：

/// file: wrangler.toml assets.directory = ".cloudflare/public" assets.binding = "ASSETS" # Exclude this if you don't have a `main` key configured.

wrangler.jsonc形式：

/// file: wrangler.jsonc { "assets": { "directory": ".cloudflare/public", "binding": "ASSETS" // Exclude this if you don't have a `main` key configured. } }

迁移完成后：

• 运行时 API 从platform.env切换为从cloudflare:workers模块导入env；
• 可通过运行wrangler types自动生成env的类型声明；
• 部署命令仍是npx wrangler deploy；
• 新增了fallback与routes（仅 Cloudflare Pages）等适配器选项，以及对_headers/_redirects文件的支持（放在项目根目录，仅对静态资源响应生效；动态响应应在 服务端路由 或 handle hook 中处理）。

九、总结

adapter-cloudflare-workers是 SvelteKit 面向 Cloudflare Workers Sites 部署模式的官方适配器，其核心工作流为：vite.config.js声明适配器 →wrangler.jsonc描述 Worker 入口与静态资源 bucket →npm run build产出单文件 Worker →wrangler deploy发布。运行时通过platform属性向 hooks 与 endpoint 暴露env/ctx/caches/cf，本地 dev/preview 环境则基于 Wrangler 配置模拟这些绑定。

由于 Cloudflare 官方已废弃 Workers Sites，新项目应直接使用adapter-cloudflare（它同样由adapter-auto在检测到 Cloudflare 环境时自动安装，见 30-adapter-auto.md），存量项目则可参照本文第八节的迁移步骤平滑切换。无论选择哪个适配器，理解 Wrangler 配置、运行时绑定注入与本地模拟机制，都是稳定落地 SvelteKit × Cloudflare 部署的关键。

• Web框架
• 后端
• 前端