部署到 Cloudflare Workers

当您的网站在请求时需要服务器时，可以部署到 Cloudflare Workers：SSR、API 路由、重定向或 Tina 可视化编辑路由。每次推送到您的生产分支都会重新构建和重新部署。

Astro

将您的项目推送到 GitHub，然后使用 Cloudflare 的基于 git 的构建或直接从您的机器进行部署。

为 Cloudflare 配置

• 使用 npx astro add cloudflare 添加 Cloudflare 适配器。它会安装 @astrojs/cloudflare 并在 astro.config.mjs 中设置 adapter: cloudflare()。
• 添加一个根 wrangler.jsonc，开启 nodejs_compat，可视化编辑路由需要它来支持 node:async_hooks：

{
  "name": "your-worker-name",
  "compatibility_date": "2026-06-01",
  "compatibility_flags": ["nodejs_compat"]
}

使用 tina-astro-starter 吗？ 这两步已经完成。它的 astro.config.mjs 从主机中选择适配器（Cloudflare 的构建设置 WORKERS_CI，在支持的适配器中选择 @astrojs/cloudflare），并且 wrangler.jsonc 已在仓库中，因此您无需运行 astro add 或编辑配置。

使用基于 git 的构建进行部署

在 Cloudflare 仪表板中，转到 Workers & Pages | Create | Workers | Import a repository，连接 GitHub，并选择您的仓库。设置：

• Build command: pnpm run build
• Deploy command: npx wrangler deploy

没有需要设置的构建输出字段。Worker 从适配器生成的配置中获取静态资产，而不是仪表板目录，Cloudflare 为您进行身份验证部署。

从 Wrangler CLI 部署

将您的 TinaCloud 凭据放在本地 .env 中，然后构建和部署：

pnpm run build
npx wrangler deploy

使用 starter 吗？ 在您自己的机器上没有设置 CI 变量，因此构建会回退到 Node 适配器。强制使用 Cloudflare：DEPLOY_ADAPTER=cloudflare pnpm run build。

环境变量

tinacms build 在构建时需要您的 TinaCloud 凭据。无论您在哪里构建都要添加它们：对于基于 git 的构建，在 Worker's Settings | Build | Variables and Secrets 下；对于 CLI 部署，在本地 .env 中。从您的 TinaCloud 项目 获取这两个凭据。

• PUBLIC_TINA_CLIENT_ID 是您的客户端 ID。Astro 使用 PUBLIC_ 前缀，而不是 Next.js 的 NEXT_PUBLIC_。
• TINA_TOKEN 是内容令牌。
• SITE_URL 是您的生产 URL，例如 https://your-worker.your-account.workers.dev。Workers 不会注入部署 URL，因此没有它，您的站点地图、RSS 和 OpenGraph 标签将回退到 localhost。

这些仅在构建时使用。tinacms build 将客户端 ID 和令牌嵌入到生成的客户端中，因此无需再次添加为运行时变量。

编辑分支

TinaCMS 在 tina/config.ts 中解析的分支上读取和写入内容，该分支来自主机的 git 环境变量。在 Cloudflare 上是 WORKERS_CI_BRANCH（Workers Builds）或 CF_PAGES_BRANCH（Pages）。将它们添加到链中：

const branch =
  process.env.GITHUB_BRANCH ||
  process.env.VERCEL_GIT_COMMIT_REF ||
  process.env.WORKERS_CI_BRANCH ||
  process.env.CF_PAGES_BRANCH ||
  process.env.HEAD ||
  "main";

没有它们，分支将回退到 main，因此预览或非 main 部署将编辑 main，而站点从您的分支构建。

使用 starter 吗？ 它的 config.ts 已经读取了这两个变量。

固定 SESSION KV 命名空间

即使您的站点不使用会话，@astrojs/cloudflare 适配器也会添加一个 SESSION KV 绑定（Astro 的会话存储）。您的第一次部署会自动创建命名空间，但 Cloudflare 不会将其 ID 写回到您的仓库，因此下一次基于 git 的部署会尝试再次创建它并失败：

✘ a namespace with this account ID and title already exists [code: 10014]

编辑器保存会触发重新部署，因此您将在第二次保存时遇到此问题。在您的根 wrangler.jsonc 中固定命名空间 ID，以便每次部署重用它。创建一个：

npx wrangler kv namespace create SESSION

或者从 Workers & Pages | KV 中复制您的第一次部署已经创建的 ID。然后将其添加到配置中：

{
  "name": "your-worker-name",
  "compatibility_date": "2026-06-01",
  "compatibility_flags": ["nodejs_compat"],
  "kv_namespaces": [{ "binding": "SESSION", "id": "<your-namespace-id>" }]
}

检查可视化编辑

部署后，在您的 Worker 的 URL 上打开 /admin，编辑一篇文章并保存。保存提交到 GitHub，触发重新部署。然后打开一个内容页面并点击一个可编辑区域：它应该高亮并在侧边栏中打开其表单。这会测试在 Worker 内运行的按需 /tina-island/* 路由。如果出现错误，请确认 nodejs_compat 已设置。

Next.js

使用 OpenNext Cloudflare 适配器 生成 open-next.config.ts 和 wrangler.jsonc。在仪表板中（Workers & Pages | Create | Workers | Import a repository），设置：

• Build command: npx opennextjs-cloudflare build
• Deploy command: npx opennextjs-cloudflare deploy

在 Settings | Build | Variables and Secrets 下添加您的构建时凭据：

• NEXT_PUBLIC_TINA_CLIENT_ID 是您的客户端 ID。
• TINA_TOKEN 是内容令牌。

如果您的 OpenNext SSR 在请求时读取这些内容，请在 Settings | Variables and Secrets 下也添加它们。

完成 TinaCloud 设置

您的第一次部署会为您提供一个域名，例如 https://<worker-name>.<account-name>.workers.dev。将其（或您的自定义域）设置为您的 TinaCloud 项目的 Site URL，以便编辑器在正确的源上加载。

故障排除

构建期间“JavaScript 堆内存不足”。 TinaCloud 索引可能会超过 Node 的默认堆。设置一个构建时 NODE_OPTIONS 变量为 --max-old-space-size=4096。