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

Web框架后端前端【免费下载链接】kitweb development, streamlined项目地址https://gitcode.com/gh_mirrors/kit/kit点击查看免费下载本指南围绕 SvelteKit 官方仓库中针对 Cloudflare WorkersWorkers 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.mdadapter-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 配置中的环境environmentpersist控制本地 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 }各字段说明字段说明name服务名称可以是任意值用于标识你的 Workeraccount_idCloudflare 账户 IDmainWorker 入口文件即 SvelteKit 构建产出的服务端文件site.bucketWorkers Sites 模式下静态资源的本地目录构建后会被上传到 KVbuild.command部署前执行的构建命令一般就是npm run buildcompatibility_dateWorker 运行时兼容性日期示例中为2021-11-12获取 account_idyour-account-id可以通过两种方式获得使用 Wrangler CLI 运行wrangler whoami登录 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 deploywrangler deploy会先按build.command触发npm run build由 SvelteKit 适配器产出 Worker 脚本与静态资源再由 Wrangler 完成上传与发布。五、运行时 API通过 platform 访问 Cloudflare 绑定在 Workers 运行时环境中env对象包含了项目的全部 bindingsKV 命名空间、Durable Object 命名空间等。adapter-cloudflare-workers通过 SvelteKit 的platform属性把这些运行时能力注入应用具体包括env项目的 bindingsctx执行上下文如waitUntilcaches缓存 APIcf请求携带的 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 devWrangler 会按配置启动本地 Worker结合site.bucket中的静态资源完整模拟生产环境的请求处理链路。七、故障排查TroubleshootingNode.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 Assets1. 替换适配器依赖与配置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 dont have a main key configured.wrangler.jsonc形式/// file: wrangler.jsonc { assets: { directory: .cloudflare/public, binding: ASSETS // Exclude this if you dont 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框架后端前端【免费下载链接】kitweb development, streamlined项目地址https://gitcode.com/gh_mirrors/kit/kit点击查看免费下载相关推荐SvelteKit Cloudflare 适配器迁移指南移除 platform、改用 cloudflare:workers 模块SvelteKit Cloudflare 适配器迁移指南移除 platform、改用 cloudflare:workers 模块 本文基于 SvelteKitWeb框架后端前端Cloudflare Browser Rendering 配置与部署实战从 wrangler.json 到 Workers Binding 完整指南Cloudflare Browser Rendering 配置与部署实战从 wrangler.json 到 Workers Binding 完整指南 Clou人工智能AI 技能AI 插件React Router 服务端适配器Server Adapters完全指南在 Express、Cloudflare、Architect 上部署与迁移React Router 服务端适配器Server Adapters完全指南在 Express、Cloudflare、Architect 上部署与迁移 导前端路由上一篇Microsoft Activation Scripts (MAS) 终极指南掌握开源Windows和Office激活方案下一篇MifareClassicTool开发者访谈项目背后的故事创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考