Cloudflare Workers SSR 全栈完全指南

本文由 Huifer 撰写，他是 TanStack Ship 的独立开发者与维护者。 在 2023 到 2026 年间，我使用 Cloudflare Workers 和 TanStack Start 交付了 12 个以上的生产级应用。本指南中提到的架构模式都已在生产环境中落地，而非仅仅在演示中看起来不错。这里描述的架构以大约 14 美元/月的成本支撑着我自己的 SaaS 运行，且冷启动时间不到 50ms。只要 Cloudflare Workers 存在局限或粗糙的地方，我也会坦承指出。

验证来源：Cloudflare Workers Docs · D1 Docs · TanStack Start Docs · TanStack Ship GitHub 最后更新：2026-07-20 · 更新日志

核心摘要： Cloudflare Workers 在边缘的 V8 隔离区（isolates）中运行 JavaScript，而不是在容器中。结合 TanStack Start 的流式 SSR、作为数据库的 D1、用于文件的 R2，以及处理后台任务的 Queues 和 Workflows，你可以获得一个快速、廉价且全球分布的全栈 SaaS 架构。本指南涵盖了整个技术栈：配置搭建、流式 SSR、D1、R2、部署、监控以及成本。同时包含了来自 12 个模块构成的真实生产环境部署的实际数据。

为什么选择 Cloudflare Workers 做 SSR？

综合以下三个原因，这种架构的选择是合理的。

1. 冷启动时间不到 50ms

Cloudflare Workers 运行在 V8 隔离区中，而非容器。没有任何容器启动时间、Node.js 引导加载或模块解析的折腾。部署后的第一个请求直接命中运行时并在几十毫秒内执行。对于 SSR 而言，首字节时间（TTFB）直接映射为用户感知的延迟，这就是“快”与“瞬间响应”之间的本质区别。

2. 成本结构显著降低

在生产环境的负载下，运行在 Cloudflare Workers 上的中型 SaaS 每月花销在 5 到 20 美元。同样的应用在基于容器的主机上每月要花费 50 到 200 美元。其计费模型是按请求计算，而不是按闲置容器计算，因此成本随实际使用量扩展，而非按照预配容量收费。

3. 平台生态高度一致

Cloudflare Workers、D1（边缘的 SQLite）、R2（兼容 S3 的存储）、Queues（消息队列）、Workflows（持久化执行）、KV（键值存储）、Durable Objects（有状态协调）—— 它们都在同一个控制面板中，使用一样的计费模式和同样的部署流程。不存在“这儿是一个 Cloudflare Workers 应用，那儿是一个 RDS 数据库、S3 存储桶、SQS 队列”这样的蔓延现象。所有的配置都在 wrangler.toml 中完成。

其中的取舍在于：Cloudflare Workers 的每一个隔离区有 128MB 的内存限制，免费计划有 CPU 时间限制，并且某些 Node.js API 无法使用。对于 SaaS 工作负载，这些都不是致命问题——但你在入坑前必须了解。我将明确指出这些限制会在哪里显现。

什么时候不应该使用 Cloudflare Workers

坦诚很关键。Cloudflare Workers 并不适合所有类型的工作负载。

占用大量 CPU 的同步任务

在付费计划中，Cloudflare Workers 的 CPU 时间限制是 30 秒，但实际最佳执行时间是低于 50ms。如果你的路由需要处理高 CPU 占用的同步工作（如图像处理、视频转码、复杂的数学模拟），那么 Cloudflare Workers 就是错误的运行时。这些工作负载应该使用基于容器的服务。

依赖长连接的应用

Cloudflare Workers 无法将单一连接保持数小时。高度依赖 WebSocket 的应用——如聊天应用、实时协作工具、视频直播——需要使用 Durable Objects 或更换其他托管方案。这一约束是 V8 隔离区模型从根本上决定的。

需要传统关系型数据库的应用

D1 的内核是 SQLite，而 SQLite 的写入吞吐量是受限的。如果你的应用需要每秒几千次的持续写入，D1 是不适合的。对于这类工作负载，你需要用一个 Queue 对接外部的 Postgres（如 Neon、Supabase、RDS），并接纳由此带来的架构复杂性。

拥有大量现有基础设施的应用

如果你已经拥有了 RDS、S3、SQS、ECS 并且运行了一年的基础设施即代码（IaC），迁移到 Cloudflare Workers 将是一次重写，而非重构。Cloudflare Workers 只能为那些愿意拥抱其原生底层规范的新项目与应用创造出最大的价值。

在 Cloudflare Workers 上配置 TanStack Start 项目

在 2026 年，最快的配置方式是使用 TanStack Start CLI：

bash

# 创建项目
npm create @tanstack/start@latest my-saas
cd my-saas

# 添加 Cloudflare Workers 适配器
npm install @tanstack/start-cloudflare-workers

# 生成 wrangler.toml 脚手架
npx wrangler init

CLI 会生成如下所示的 wrangler.toml：

toml

name = "my-saas"
main = "./dist/server/index.js"
compatibility_date = "2026-07-01"
compatibility_flags = ["nodejs_compat"]

[[d1_databases]]
binding = "DB"
database_name = "my-saas-prod"
database_id = "your-database-id"

[[r2_buckets]]
binding = "STORAGE"
bucket_name = "my-saas-uploads"

[[queues.producers]]
binding = "BILLING_QUEUE"
queue = "billing-events"

[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

[vars]
APP_ENV = "production"

每个 [[bindings]] 块都为你的 Cloudflare Workers 提供了一个带类型的绑定——如 env.DB、env.STORAGE 等——这些绑定能在 Server Functions 内访问。nodejs_compat 标志用于为需要 Node.js API 兼容的库开启 polyfill。

如需完整的 TanStack Start 部署演练，请参阅 TanStack Ship 功能页；有关路由模式，请见流式 SSR 指南。

流式 SSR：工作原理

流式 SSR（Streaming SSR）技术允许服务器在每部分 HTML 就绪时立即将其发送给浏览器，而不是等到整页渲染完毕才传输字节。

在 React 19 中，这是通过 <Suspense> 边界实现的。每个 Suspense 边界在其完全解析后会立即将内容分发给浏览器：

tsx

// app/dashboard/page.tsx
import { Suspense } from "react";
import { LoadingSkeleton } from "~/components/loading-skeleton";

export default function DashboardPage() {
  return (
    <main>
      <h1>Dashboard</h1>

      {/* 立即发送 */}
      <Suspense fallback={<LoadingSkeleton />}>
        <RecentOrders /> {/* 异步服务端组件 — 就绪时采用流式传输 */}
      </Suspense>

      {/* 立即发送 */}
      <Suspense fallback={<LoadingSkeleton />}>
        <MonthlyRevenue /> {/* 异步服务端组件 — 就绪时采用流式传输 */}
      </Suspense>
    </main>
  );
}

浏览器首先会立即收到页面骨壳，然后随着每个部分的解析，收到最近订单和月度收入内容。首字节时间（TTFB）从“渲染整个页面所需的时间”降至“渲染页面骨架所需的时间”。

这带来的性能影响是：在真实生产环境中，流式 SSR 将典型 SaaS 仪表板的 TTFB 中位数从约 180ms 降至约 40ms。这就是“感觉很快”和“感觉立刻发生”的区别。

流式传输最能发挥威力的地方

流式传输在具备多个异步数据源的页面上效果显著。一个加载用户信息、账单状态和通知的登录页可以并行流式传输这三部分数据，而不是串行排队。一个加载商品信息、库存、点评详情的产品页也能并发处理这三块。

在单一数据源的页面上，流式传输的帮助不大。如果只有一个数据需要等待，就没有什么内容可以率先流式传输。

能够平滑扩展的模式 vs 无法扩展的模式

在 Cloudflare Workers 上，有两种模式可以很好地扩展，另外两种则不行。

平滑扩展： 许多小型独立查询通过 Suspense 并行解析。框架自动扇出，隔离区并发解析，用户能在极速的 TTFB 响应中看着内容逐渐填满。

平滑扩展： 在 10-50ms 内完成的同步单一查询路由。这个请求刚好契合单一的 CPU 时间预算，不需要重试，也不涉及异步协调。

无法平滑扩展： 单个路由触发 10 次串行查询并等待逐个完成。总处理时间是累加的；用户只能一直干等。

无法平滑扩展： 路由加载一个庞大数据集（数兆字节）并在内存中将其序列化后返回。你会直接撞上 128MB 的内存限制与 CPU 时间预算。这类场景请使用分页。

规律是：控制路由上的工作范围，通过 Suspense 边界并发执行任务，并尽可能采用流式传输。

D1：位于边缘的数据库

D1 是 Cloudflare 提供的分布式 SQLite 数据库。读取操作会复制到每一个区域；写入操作则被发往主区域随后同步。对于每个区域每秒不到几百次写入的 SaaS 工作负载，D1 是你能找到的最便宜且最快的数据库方案。

Schema 与数据迁移

最标准的模式是将 Drizzle ORM 与数据迁移工作流搭配使用：

// db/schema.ts
import { sqliteTable, integer, text } from "drizzle-orm/sqlite-core";

export const users = sqliteTable("users", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  email: text("email").notNull().unique(),
  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
});

export const subscriptions = sqliteTable("subscriptions", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  userId: integer("user_id").references(() => users.id).notNull(),
  status: text("status").notNull(),
  stripeCustomerId: text("stripe_customer_id").notNull(),
});

bash

# 生成迁移
npx drizzle-kit generate

# 本地应用
npx wrangler d1 migrations apply my-saas-prod --local

# 生产环境应用
npx wrangler d1 migrations apply my-saas-prod --remote

写入锁限制

D1 的写入锁在每个数据库范围内全局生效。当写入量高于 60 req/s 时，锁竞争就开始浮现。当高于 200 req/s 时，竞争就会占据主导。解决办法是将写入放入 Cloudflare Queue + Workflow 管道处理——这在 D1 写入锁事故复盘中被详细说明。对于流量相对较低的 SaaS 负载，同步写入完全没有问题。

关于更深入的 D1 模式，请参阅 D1 生产环境指南和 D1 查询优化技巧。

R2：文件存储

R2 是一种兼容 S3 的对象存储，且出站流量免费（零传出费）。零流量费的这点细节比听起来有用的多：如果 SaaS 每次页面访问都需要下发用户上传的图片，在 AWS 那边会产生一笔可观的账单；而在 R2 上运行同样的工作负载，存储与分发路径几乎可以说是免费的。

使用模式

// 上传处理器
export const uploadAvatar = createServerFn().handler(async ({ data }) => {
  const key = `avatars/${crypto.randomUUID()}`;
  await env.STORAGE.put(key, data.file, {
    httpMetadata: { contentType: data.file.type },
  });
  return { key, url: `https://cdn.example.com/${key}` };
});

// 通过绑定到 R2 存储桶的自定义域名进行分发
// (在 Cloudflare 面板中配置，无需在代码里写)

为你的 R2 存储桶绑定一个自定义域名以获得 CDN 专属 URL。这一配置是在 Cloudflare 控制面板中进行的一步操作；代码中不必再去构建签名 URL，因为自定义域名已直接将存储桶公开。

Queues + Workflows：后台异步任务

这两种底层能力共同使用几乎涵盖每一项后台异步任务。

Queues 队列

Cloudflare Queues 是一种保障至少投递一次的消息队列。常用于：Webhook 扇出分发、触发邮件、批量写入、可重试的低配任务。

// 生产者
await env.BILLING_QUEUE.send({
  type: "subscription.renewed",
  payload: { userId: 123, amount: 4900 },
});

// 消费者
export default {
  async queue(batch: MessageBatch<unknown>, env: Env) {
    for (const msg of batch.messages) {
      await processBillingEvent(msg.body, env);
      msg.ack();
    }
  },
};

Workflows 工作流

Cloudflare Workflows 具备带有重试、休眠等待以及基于步骤进行组合编排的持久化执行能力。你可以用它来处理：多步骤的激活流程、定时作业、带回退机制（backoff）的复杂重试逻辑。

// 工作流定义
export class OnboardingWorkflow implements Workflow {
  async run(event: Payload, step: WorkflowStep) {
    await step.do("create-account", async () => createAccount(event));
    await step.sleep("wait-24h", "24h");
    await step.do("send-day-1-email", async () => sendEmail(event));
  }
}

这两者的组合——用于触发即可遗忘（fire-and-forget）事件的 Queue，对接管理多步骤持久化流程的 Workflow——覆盖了 SaaS 中 95% 的后台作业。剩下的 5% 主要是指 Durable Objects 处理的有状态协调任务（如聊天室、多人游戏并发、硬性限制管控）。

部署

bash

# 生产环境部署
npx wrangler deploy

# 管理安全机密
npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put RESEND_API_KEY

# 追踪日志
wrangler tail --format=pretty

# D1 统计分析
wrangler d1 insights --database=my-saas-prod

第一次部署大约需要 30 秒；随后的每次部署不到 10 秒就能跑完。位于 dash.cloudflare.com 的控制面板展示了请求数、错误量、CPU 耗时以及按路由细分的统计分析。对于深度可观测性监控，利用 Logpush 把 wrangler tail 推发到 Datadog 或 Grafana。

监控与日志

在每一个 Cloudflare Workers 应用中，我都会盯紧这三个指标：

每条路由的 CPU 时间 p99。 Cloudflare Workers 按 CPU 时长计费；运行久的长路由支出更高。如果 p99 突过 50ms 一线，需要开始警戒并排查。
每条路由的错误率。 Cloudflare 面板呈现了该信息；告警可以经由 webhook 送往 Discord。
D1 的 write_lock_wait_ms。 这构成了早前写入锁危机形态显露时的预警信号核心。

bash

# 极简定时告警示例
watch -n 60 'wrangler d1 insights --database=my-saas-prod | grep write_lock'

也可以选择借助 Logpush 推流到 Datadog 做告警触发。工具配套选择并不唯一，核心宗旨是必须构建对这三大数据的持续预警习惯。

成本分析

采用我的生产级平台数据进行演算（就是部署在 TanStack Ship 项目）：

Cloudflare Workers: 每月约 500 万次请求，成本约为 $5/月
D1: 20 万次读取 + 5 万次写入，成本约为 $4/月
R2: 存储 10GB 数据 + 50GB 传出耗流，成本约为 $1/月
Queues: 100 万条消息运转，成本约为 $1/月
Workflows: 5 万个工作步骤调度与执行，成本约为 $1/月
KV: 10 万次拉取配置访问，成本约为 $2/月

汇总算下来：为拥有 3,200 名客户的 SaaS 负载完全的 SSR 框架应用、下放的库数据存放、底层云空间储放加之后台队列作业，单月估价约在 14 美元。同质量挂靠 AWS 同级组合大概为 $80-150/月；移值至 Vercel 结合数据库配置约需要 $60-100/月之间。

你必须要了解的能力局限

Cloudflare Workers 带有其硬性前提限制规则，进场之前你必须清楚。

每个隔离区有 128MB 的内存上限

这类指标规模对普通的日常 SaaS 事务通常不成阻碍。不过每当在加载超出庞杂度容量基准的长信息流或者提取文件序列处理时请主动采用分页请求甚至传输卸载形式进行化整为零的处理分流举措。

CPU 时间限制

按照其不充值的基础款规则：免费方案会将每次执行单次流的上限卡住在 10ms CPU 基期上。正常高流量运转商业客户其标准界限被控于在 50ms 或者非限使用机制 (Unbound) 放开了每次 30 秒的时差空间。寻常意义下的所有 SSR 调用基本上都涵盖在了不到 50ms 框架限域，而超出往往牵扯极高强度的数据库串联以及复杂的超图片数据转码需求。

无法维持长连通信

在 Cloudflare Workers 并不能对 WebSocket 持续开放至半点几刻之上。有关的长线实时间保持沟通事务必须指交给专管应对任务的长时限 DO 组件体系。凡是业务需长续即时通话都一概要在 DO 落点安排统筹进行方案拟定。

`nodejs_compat` 涵盖了大多数而非全部的 Node API 补充兼容

市面上部分 npm 辅助性组件基于对 Node 服务本质基础运转逻辑模型有着独占的开发基础依赖因此难被有效激活，好在这种应用模型中的 nodejs_compat 将对应的缺失做出了高度容忍度的修补填进；只对于最极端的小类别库支持需在未来做备选切换计划准备工作。时至 2026 它们仍然非常低发但依旧会出现此麻烦存在现象发生的几率。

缺乏原生本地传统读写的操作文件框架支持

不能像往常代码中写入依赖对 fs 类属性操作体系行使常规任务执行。所有的文件交相查理互动都需要通过指定的流转平台比如是 D1、R2、KV、以及有向调令组件的 DO 通路。构建现代的 SaaS 项目一般在设计中不太会被这一短板捆住限制脚力，一旦潜意识又意图采用普通读去取写思路调用 fs.readFile 去行事操作时，那么此时你要在脑中拉一次警报考量另辟方案应对去进行妥善执行规划实施战略处理调整计划设定准备动作指引思考框架转换了！

将一切组合起来

基于 Cloudflare Workers 设置的全盘架构 SaaS 生产形态模式为：

TanStack Start 负责整体项目 SSR、路由及安全形式下数据层流通传引载入
Cloudflare Workers 提供稳固的高性效能边缘运行时环境执行基座
D1 为数据库管理储存执行云平台（基于边缘化分布式 SQLite）
R2 服务做无宽带分发限价开销负担特点形式下稳定输出上传的静态网络云层库（免费流出 CDN 体系）
Queues 容载所有的并列排单批量传导发事件以处理后端写入序列业务调配工作
Workflows 接引各类高持久稳固形式的时序或串多段复杂业务运转调度执行护航指引
Durable Objects 于维持关键常驻或者必须时序绝对硬锁性规则的互动应用中（管控网域访问速率流速监管与实时全长段连结传导维系管控策略支持）发挥枢纽掌控指引地位
KV 主要部署为全局最精巧高能缓存及项目总局下微小的环境分级亮控指示标志派发存储定位中心
Stripe + Resend 处理有资金流结算回账相关的及应用外置传叫发信发送任务事件工作环节（作为发起与挂接来自外延请求的 Workers 调用处理动作上极具轻盈优劣强适应性特点表现水平极好）

依托这构架搭配使得现在的 TanStack Ship 可在以低于 50ms 起手发跑热速，不仅能保障有超高容准表现下稳定高达了 99.95% 的顺接性指标呈现记录数据，更是单在运转支撑支出花费额度能极低做到了按月仅以 14 美元维持跑盘运作表现。这些归纳呈现梳理写进记录分享出来的配置方法与处理模式理念也是这 2026 我们推荐提供于各位想要并意图在此平台上扎下建构 SaaS 事业团队应遵守参考实践行动的坚稳终极首推解答参考策略方略准则大全范册。

想阅取更细分探索讨论文章的路径，建议深研前往流式化框架 SSR 基本规则揭秘解读分析导源说明原理概述指南书篇、参考通览 2026 SaaS 系统科技架型开发建组选取考衡测查抉议战略指南总览通释书解章乃至 TanStack Ship 功能统要全录梳理总汇通略大纲展示介页表录处栏去对应探索寻找对照去核准匹配进行印章引引印引阅览检索获取相关资料阅读探查浏览详见。。

即可启航运转试用这 TanStack Ship 板配方案包程序进行探索引领出发吧 — 这是一个集容包含带有这 14 名板块内核搭建立在用在此 Cloudflare Workers 基座环境上构成的全备云 SaaS 系统原生开初模带样启动开发工程起始库引擎板项目底色范架初制开版。现在这里免费抓下起始首支克隆建工程样构初始库开始去试推着运行摸体验吧 → · 去看对应的项目定位及查阅其全套系价表说与及相关可通商许可明项条例则信息详细条款栏页

为什么选择 Cloudflare Workers 做 SSR？

1. 冷启动时间不到 50ms

2. 成本结构显著降低

3. 平台生态高度一致

什么时候不应该使用 Cloudflare Workers

占用大量 CPU 的同步任务

依赖长连接的应用

需要传统关系型数据库的应用

拥有大量现有基础设施的应用

在 Cloudflare Workers 上配置 TanStack Start 项目

流式 SSR：工作原理

流式传输最能发挥威力的地方

能够平滑扩展的模式 vs 无法扩展的模式

D1：位于边缘的数据库

Schema 与数据迁移

写入锁限制

R2：文件存储

使用模式

Queues + Workflows：后台异步任务

Queues 队列

Workflows 工作流

部署

监控与日志

成本分析

你必须要了解的能力局限

每个隔离区有 128MB 的内存上限

CPU 时间限制

无法维持长连通信

nodejs_compat 涵盖了大多数而非全部的 Node API 补充兼容

缺乏原生本地传统读写的操作文件框架支持

将一切组合起来

`nodejs_compat` 涵盖了大多数而非全部的 Node API 补充兼容