部署 | TanStarter - Ship Faster with TanStack, Cost Less with Cloudflare

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

前提条件

在将项目部署到 Cloudflare Workers 之前，请确保您有Cloudflare 账户，如果您没有，请在这里注册

关于 Worker 大小限制的说明

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

Total Upload: 10421.14 KiB / gzip: 2241.95 KiB

TanStarter 模板的大小大概为 2 MB，因此即使您是 Cloudflare 免费计划也可以部署。

部署前准备

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

项目初始化：按照快速开始文档完成项目初始化、依赖安装和本地运行
Cloudflare API Token：按照 Cloudflare API Token 文档完成 Token 配置
数据库设置：按照数据库文档完成本地和远程数据库的创建和初始化
存储设置：如果网站需要文件存储功能，按照存储文档创建存储桶
环境变量配置：按照环境配置文档配置网站所需功能的必要环境变量

部署步骤

配置项目名称

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

wrangler.jsonc

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

配置自定义域名

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

wrangler.jsonc

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

关于自定义域名的说明

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

配置生产环境变量

设置生产环境运行时的环境变量，参考下面的流程，先复制 .env 文件为 .env.production 文件，然后修改部分环境变量改为生产环境值，最后批量设置密钥。

请确保 Cloudflare API Token 包含 Account > Workers Scripts > Edit 权限，否则可能会报错。

# 复制.env 文件为 .env.production 文件
cp .env .env.production

# 请将 .env.production 文件中的部分环境变量改为生产环境值
# 例如：VITE_BASE_URL、STRIPE_SECRET_KEY 等
# VITE_BASE_URL='https://your-domain.com'
# STRIPE_SECRET_KEY='your-stripe-live-secret-key'

# 批量设置密钥
pnpm wrangler secret bulk .env.production

# 设置单个密钥
echo "your-secret" | pnpm wrangler secret put VITE_BASE_URL

这步执行成功之后，您可以在 Cloudflare 仪表盘的 Workers & Pages 中看到新建的项目。

关于环境变量文件的说明

环境变量文件 .env.production 是生产环境运行时的环境变量文件，用于配置生产环境运行时的环境变量。在下一步执行 pnpm run deploy 命令时，会自动读取 .env.production 文件中的环境变量。
环境变量文件 .env 是本地开发环境运行时的环境变量文件，用于配置本地开发环境运行时的环境变量。在日常开发执行 pnpm run dev 命令时，会自动读取 .env 文件中的环境变量。

部署到 Cloudflare

将应用程序部署到 Cloudflare Workers，执行下面的命令进行构建和部署。

请确保 Cloudflare API Token 包含 Zone > Workers Routes > Edit 权限，否则可能会报错。

pnpm run deploy

这步执行成功之后，您可以在新项目中看到刚部署的版本，并且通过自定义域名访问网站。

关于自定义域名的说明

如果您还没有域名，可以使用 Cloudflare 提供的默认域名，一般是 https://{worker-name}-{account-name}.workers.dev，注意修改 .env.production 文件中的环境变量。
如果您已经有了域名，那么需要将自定义域名绑定到 Cloudflare 平台托管，或者按照后台仪表盘中设置界面中绑定自定义域名的流程配置 DNS 记录，正确解析到 Cloudflare 平台。

绑定 GitHub 仓库

前面已经通过命令行创建好了 Worker 项目，接下来需要将 GitHub 仓库连接到该项目，实现代码推送后自动构建部署。

进入 Cloudflare 仪表盘，导航到 Workers & Pages
点击前面创建的 Worker 项目，进入项目详情页
进入 Settings → Build，点击 Connect 连接 GitHub 仓库
选择您的 GitHub 仓库并授权
配置构建命令和部署命令（使用默认值即可）：
- Build command：pnpm run build
- Deploy command：npx wrangler deploy
配置编译时环境变量：添加环境变量文件中所有以 VITE_ 开头的环境变量

关于环境变量的说明

编译时环境变量只能在仪表盘中配置，无法通过命令行或配置文件设置。这些变量在构建阶段由 Vite 读取，主要是以 VITE_ 开头的客户端变量。服务端运行时变量则通过 wrangler secret 命令配置，详见上一步。
如果您希望代码提交到 GitHub 仓库之后，自动触发 Cloudflare Worker 项目的构建和部署，那么就必须将环境变量文件中所有以 VITE_ 开头的环境变量都添加到编译时环境变量中，才能保证网站正常运行。

参考资料

下一步

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

数据库

配置 D1 数据库

存储

配置 R2 存储

支付

配置 Stripe 支付

身份验证

配置身份验证

部署

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

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

前提条件

在将项目部署到 Cloudflare Workers 之前，请确保您有Cloudflare 账户，如果您没有，请在这里注册

关于 Worker 大小限制的说明

Total Upload: 10421.14 KiB / gzip: 2241.95 KiB

TanStarter 模板的大小大概为 2 MB，因此即使您是 Cloudflare 免费计划也可以部署。

部署前准备

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

项目初始化：按照快速开始文档完成项目初始化、依赖安装和本地运行
Cloudflare API Token：按照 Cloudflare API Token 文档完成 Token 配置
数据库设置：按照数据库文档完成本地和远程数据库的创建和初始化
存储设置：如果网站需要文件存储功能，按照存储文档创建存储桶
环境变量配置：按照环境配置文档配置网站所需功能的必要环境变量

部署步骤

配置项目名称

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

wrangler.jsonc

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

配置自定义域名

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

wrangler.jsonc

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

关于自定义域名的说明

配置生产环境变量

请确保 Cloudflare API Token 包含 Account > Workers Scripts > Edit 权限，否则可能会报错。

# 复制.env 文件为 .env.production 文件
cp .env .env.production

# 请将 .env.production 文件中的部分环境变量改为生产环境值
# 例如：VITE_BASE_URL、STRIPE_SECRET_KEY 等
# VITE_BASE_URL='https://your-domain.com'
# STRIPE_SECRET_KEY='your-stripe-live-secret-key'

# 批量设置密钥
pnpm wrangler secret bulk .env.production

# 设置单个密钥
echo "your-secret" | pnpm wrangler secret put VITE_BASE_URL

这步执行成功之后，您可以在 Cloudflare 仪表盘的 Workers & Pages 中看到新建的项目。

关于环境变量文件的说明

环境变量文件 .env.production 是生产环境运行时的环境变量文件，用于配置生产环境运行时的环境变量。在下一步执行 pnpm run deploy 命令时，会自动读取 .env.production 文件中的环境变量。
环境变量文件 .env 是本地开发环境运行时的环境变量文件，用于配置本地开发环境运行时的环境变量。在日常开发执行 pnpm run dev 命令时，会自动读取 .env 文件中的环境变量。

部署到 Cloudflare

将应用程序部署到 Cloudflare Workers，执行下面的命令进行构建和部署。

请确保 Cloudflare API Token 包含 Zone > Workers Routes > Edit 权限，否则可能会报错。

pnpm run deploy

这步执行成功之后，您可以在新项目中看到刚部署的版本，并且通过自定义域名访问网站。

关于自定义域名的说明

如果您还没有域名，可以使用 Cloudflare 提供的默认域名，一般是 https://{worker-name}-{account-name}.workers.dev，注意修改 .env.production 文件中的环境变量。
如果您已经有了域名，那么需要将自定义域名绑定到 Cloudflare 平台托管，或者按照后台仪表盘中设置界面中绑定自定义域名的流程配置 DNS 记录，正确解析到 Cloudflare 平台。

绑定 GitHub 仓库

前面已经通过命令行创建好了 Worker 项目，接下来需要将 GitHub 仓库连接到该项目，实现代码推送后自动构建部署。

进入 Cloudflare 仪表盘，导航到 Workers & Pages
点击前面创建的 Worker 项目，进入项目详情页
进入 Settings → Build，点击 Connect 连接 GitHub 仓库
选择您的 GitHub 仓库并授权
配置构建命令和部署命令（使用默认值即可）：
- Build command：pnpm run build
- Deploy command：npx wrangler deploy
配置编译时环境变量：添加环境变量文件中所有以 VITE_ 开头的环境变量

关于环境变量的说明

编译时环境变量只能在仪表盘中配置，无法通过命令行或配置文件设置。这些变量在构建阶段由 Vite 读取，主要是以 VITE_ 开头的客户端变量。服务端运行时变量则通过 wrangler secret 命令配置，详见上一步。
如果您希望代码提交到 GitHub 仓库之后，自动触发 Cloudflare Worker 项目的构建和部署，那么就必须将环境变量文件中所有以 VITE_ 开头的环境变量都添加到编译时环境变量中，才能保证网站正常运行。

参考资料

下一步

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

数据库

配置 D1 数据库

存储

配置 R2 存储

支付

配置 Stripe 支付

身份验证

配置身份验证

部署

前提条件

部署前准备

部署步骤

配置项目名称

配置自定义域名

配置生产环境变量

部署到 Cloudflare

绑定 GitHub 仓库

参考资料

下一步

数据库

存储

支付

身份验证

目录

部署

前提条件

部署前准备

部署步骤

配置项目名称

配置自定义域名

配置生产环境变量

部署到 Cloudflare

绑定 GitHub 仓库

参考资料

下一步

数据库

存储

支付

身份验证

目录