跳过主要内容
文档目录

部署网站

学习如何将您的 MinuteShip 项目部署到 Cloudflare Workers

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

部署前准备

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

  1. 项目初始化：按照 快速开始 文档完成初始化、依赖安装和本地运行
  2. 环境变量配置：按照 环境配置 文档配置网站所需功能的必要环境变量
  3. 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
  }
],

Warning

关于自定义域名的说明

以上配置适用于域名已由 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

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

  1. 同步 .env.production 与 deploy.yml：确保 GitHub Actions 工作流的 env 块包含 .env.production 中定义的所有构建时变量（VITE_*、CLOUDFLARE_*）。如果缺少环境变量，会自动添加。

  2. 推送密钥到 GitHub：从 .env.production 读取所有非空变量，通过 gh secret set 将它们设置为 GitHub Secrets。请确保文件 .env.production 存在且 gh 已安装并完成账号认证。

Warning

前置条件

  • 必须已登录 GitHub CLI：gh auth status
  • .env.production 文件必须包含构建时的环境变量
  • 所有非空变量都会上传到 GitHub Secrets；只有 VITE_* 与 CLOUDFLARE_* 名称会添加到工作流 env 中

设置运行时环境变量

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

pnpm sync-worker-secrets

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

Warning

关于运行时密钥的说明

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

构建与部署

手动构建

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

pnpm run deploy

自动构建

模板支持通过 Github Actions 自动化构建和部署。

工作流文件位于 .github/workflows/deploy.yml，每次向 main 分支推送代码时都会自动构建和部署。

启用工作流：前往 GitHub 仓库的 Actions 选项卡，如有提示请启用 "Github Actions"。

工作流程：每次推送到 main 分支，工作流将：

  1. 拉取代码
  2. 安装依赖
  3. 执行只读 pnpm lint 和 pnpm test（先编译语言模块）
  4. 使用 GitHub Secrets 中的构建时环境变量执行 pnpm build
  5. 执行 pnpm typecheck，使用构建生成的类型
  6. 全部通过后，通过 wrangler deploy 部署到 Cloudflare Workers

此工作流不包含浏览器 E2E。手动 pnpm run deploy 仅构建和部署；发布前请另行运行 pnpm check 和 pnpm check:production。

您可以在仓库的 Actions 选项卡中监控部署进度和结果。

您也可以通过在 Cloudflare Worker 后台绑定 Github 仓库来触发自动构建和部署，但是 Cloudflare 平台的构建失败率较高，问题较多，个人不推荐使用，更推荐使用 Github Actions 来自动化构建和部署。

环境变量对比

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

Warning

为什么两者都需要

  • 构建时密钥：必须在构建时注入，因为它们嵌入在客户端 bundle 中，更改它们需要重新构建。
  • 运行时密钥：需要单独上传到 Worker。仅保存到 GitHub Secrets 不会配置 Worker 运行时；当前部署工作流不执行 Worker 密钥同步。

参考资料

下一步

现在您了解了如何将网站部署到 Cloudflare Workers，请探索其他相关主题：