部署网站
学习如何将您的 ShipSaaS 项目部署到 Cloudflare Workers
本文档将帮助您将 ShipSaaS 项目部署到 Cloudflare Workers。
关于 Worker 大小限制的说明
Cloudflare Worker 在 Workers 免费计划上的大小限制为 3 MB，在 Workers 付费计划上为 10 MB。构建 Worker 后，wrangler 将显示原始大小和压缩大小，只有后者（压缩大小）对 Worker 大小限制重要。
Total Upload: 10421.14 KiB / gzip: 2241.95 KiBShipSaaS 模板的大小大概为 2.3 MB，因此即使您是 Cloudflare 免费计划也可以部署。但是，如果您需要使用 Cloudflare Email Service，那么您必须付费。推荐你升级为 Worker Paid Plan，功能更多，免费额度更多。
部署前准备
在部署之前，请确保您已经完成以下准备工作：
- 项目初始化：按照 获取 ShipSaaS 文档完成初始化、依赖安装和本地运行
- 环境变量配置：按照 环境配置 文档配置网站所需功能的必要环境变量
部署步骤
配置项目名称
在 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：
bun run 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 设置运行时环境变量：
bun run sync-worker-secrets此命令内部执行 wrangler secret bulk .env.production，从 .env.production 读取非空变量并通过 Wrangler CLI 批量设置为 Worker 运行时密钥。
关于运行时密钥的说明
- 运行时密钥在 Worker 执行时通过
process.env注入。 VITE_*前缀的环境变量会被自动排除，因为它们仅用于构建时。- 如需更新运行时密钥，重新执行
bun run sync-worker-secrets。
构建与部署
手动构建
如果您偏好手动构建和部署，执行下面的命令：
bun run deploy自动构建
模板支持通过 Github Actions 自动化构建和部署。
工作流文件位于 .github/workflows/deploy.yml，每次向 main 分支推送代码时都会自动构建和部署。
启用工作流：前往 GitHub 仓库的 Actions 选项卡，如有提示请启用 "Github Actions"。
工作流程：每次推送到 main 分支，工作流将：
- 拉取代码
- 安装依赖
- 使用 GitHub Secrets 中的构建时环境变量进行构建
- 通过
wrangler deploy部署到 Cloudflare Workers
您可以在仓库的 Actions 选项卡中监控部署进度和结果。
您也可以通过在 Cloudflare Worker 后台绑定 Github 仓库来触发自动构建和部署，但是 Cloudflare 平台的构建失败率较高，问题较多，个人不推荐使用，更推荐使用 Github Actions 来自动化构建和部署。
环境变量对比
| 类型 | 命令 | 使用时机 | 示例 |
|---|---|---|---|
| 构建时密钥 | bun run sync-github-secrets | 构建时 | VITE_BASE_URL、VITE_STRIPE_PRICE_* |
| 运行时密钥 | bun run sync-worker-secrets | Worker 运行时 | STRIPE_SECRET_KEY、BETTER_AUTH_SECRET |
为什么两者都需要
- 构建时密钥：必须在构建时注入，因为它们嵌入在客户端 bundle 中，更改它们需要重新构建。
- 运行时密钥：无法通过 GitHub Secrets 设置，因为 Worker 在运行时读取它们，而非在构建时。
参考资料
下一步
现在您了解了如何将网站部署到 Cloudflare Workers，请探索其他相关主题：