部署网站

本文档将帮助您将 TanStarter 项目部署到 Cloudflare Workers。

关于 Worker 大小限制的说明

Cloudflare Worker 在 Workers 免费计划上的大小限制为 3 MB，在 Workers 付费计划上为 10 MB。构建 Worker 后，wrangler 将显示原始大小和压缩大小，只有后者（压缩大小）对 Worker 大小限制重要。

Total Upload: 10421.14 KiB / gzip: 2241.95 KiB

TanStarter 模板的大小大概为 2.3 MB，因此即使您是 Cloudflare 免费计划也可以部署。但是，如果您需要使用 Cloudflare Email Service，那么您必须付费。推荐你升级为 Worker Paid Plan，功能更多，免费额度更多。

部署前准备

在部署之前，请确保您已经完成以下准备工作：

项目初始化：按照快速开始文档完成初始化、依赖安装和本地运行
环境变量配置：按照环境配置文档配置网站所需功能的必要环境变量
Cloudflare 绑定：如果使用 D1、R2 或 KV 缓存，请确保部署前已经在 wrangler.jsonc 中配置对应绑定

部署步骤

配置项目名称

在 wrangler.jsonc 文件中更新您的项目名称：

wrangler.jsonc

{
  "name": "your-project-name" // 更改为您的项目名称
}

配置自定义域名

在 wrangler.jsonc 文件中更新您的网站域名：

wrangler.jsonc

"routes": [
  {
    "pattern": "your-domain.com", // 更改为您的域名
    "custom_domain": true
  }
],

关于自定义域名的说明

以上配置适用于域名已由 Cloudflare 托管并且没有配置 DNS 的情况。如果您的域名尚未托管在 Cloudflare，可以先删除 routes 配置，待部署完成之后，再前往 Cloudflare 仪表盘手动绑定自定义域名。

准备环境变量

将 .env 复制为 .env.production 并更新为生产环境值，注意修改部分环境变量值为生产环境下的值：

cp .env .env.production

# 编辑 .env.production 配置生产环境值
# VITE_BASE_URL='https://your-domain.com'
# STRIPE_SECRET_KEY='your-stripe-live-secret-key'
# 其他环境变量，仔细检查需要修改为生产环境下的环境变量值

设置编译时环境变量

运行以下命令将构建时环境变量同步到 GitHub Secrets：

pnpm sync-github-secrets

该脚本内部执行两个操作：

同步 .env.production 与 deploy.yml：确保 GitHub Actions 工作流的 env 块包含 .env.production 中定义的所有构建时变量（VITE_*、CLOUDFLARE_*）。如果缺少环境变量，会自动添加。
推送密钥到 GitHub：从 .env.production 读取所有非空变量，通过 gh secret set 将它们设置为 GitHub Secrets。请确保文件 .env.production 存在且 gh 已安装并完成账号认证。

前置条件

必须已登录 GitHub CLI：gh auth status
.env.production 文件必须包含构建时的环境变量
VITE_* 前缀和 CLOUDFLARE_* 前缀的环境变量默认都会同步到 Github

设置运行时环境变量

运行以下命令为 Worker 设置运行时环境变量：

pnpm sync-worker-secrets

此命令内部执行 wrangler secret bulk .env.production，从 .env.production 读取非空变量并通过 Wrangler CLI 批量设置为 Worker 运行时密钥。

关于运行时密钥的说明

运行时密钥在 Worker 执行时通过 process.env 注入。
VITE_* 前缀的环境变量会被自动排除，因为它们仅用于构建时。
如需更新运行时密钥，重新执行 pnpm sync-worker-secrets。

构建与部署

如果您偏好手动构建和部署，执行下面的命令：

pnpm run deploy

环境变量对比

类型	命令	使用时机	示例
构建时密钥	`pnpm sync-github-secrets`	构建时	`VITE_BASE_URL`、`VITE_STRIPE_PRICE_*`
运行时密钥	`pnpm sync-worker-secrets`	Worker 运行时	`STRIPE_SECRET_KEY`、`BETTER_AUTH_SECRET`

为什么两者都需要

构建时密钥：必须在构建时注入，因为它们嵌入在客户端 bundle 中，更改它们需要重新构建。
运行时密钥：无法通过 GitHub Secrets 设置，因为 Worker 在运行时读取它们，而非在构建时。