部署 Web | EasyStarter Docs

部署 Web（Cloudflare Workers）

EasyStarter 的 Web 应用基于 TanStack Start，以 SSR 模式运行在 Cloudflare Workers 上。Web Worker 通过 Service Bindings 与 Server Worker 直连，无需经过公网。

部署 Web 前，必须先完成 Server 部署。 Service Binding 依赖 Server Worker 已存在。

EasyStarter 支持两种部署方式，按需选择：

方式	适合场景
方式一：本地 CLI 部署	快速上线、一次性部署、完全手动控制
方式二：GitHub 自动部署	持续交付、团队协作、推送即部署

方式一：本地 CLI 部署

本地登录 Wrangler 后，手动执行部署命令。

npx wrangler login

环境变量说明

Web 端的所有变量都是 VITE_ 前缀的公开配置，Vite 在构建时会将其注入到前端代码中。无需 Secrets，全部放在 wrangler.jsonc 的 vars 中即可。

类型	文件	说明
本地开发	`apps/web/.env.development`	本地 `wrangler dev` 自动加载，指向 localhost
生产部署	`apps/web/wrangler.jsonc` → `vars`	随代码构建打包，部署到 Cloudflare

Web 端不需要 .env.production 或 wrangler secret bulk——所有变量均为公开值。

更新 `apps/web/wrangler.jsonc`

填入 Worker 名称、Server Service Binding 和公开变量：

apps/web/wrangler.jsonc

{
  "name": "your-web-worker",            // Web Worker 名称，全局唯一
  "compatibility_date": "2025-09-02",
  "compatibility_flags": ["nodejs_compat"],
  "main": "@tanstack/react-start/server-entry",
  "assets": {
    "not_found_handling": "single-page-application"
  },
  "services": [
    {
      "binding": "API_SERVICE",
      "service": "your-server-worker"   // 必须与 Server wrangler.jsonc 的 name 完全一致
    }
  ],
  "vars": {
    "VITE_SERVER_URL": "https://your-server-worker.your-subdomain.workers.dev",
    "VITE_APP_URL": "https://your-web-worker.your-subdomain.workers.dev"
  }
}

字段	说明
`name`	Web Worker 名称，决定默认访问 URL
`services[0].service`	必须与 Server 的 `name` 完全一致，否则 Service Binding 无法建立
`vars.VITE_SERVER_URL`	Server 地址，用于 oRPC 客户端和 Better Auth 客户端
`vars.VITE_APP_URL`	Web 应用自身地址，用于 SEO 规范链接、OAuth 回调等

部署 Web Worker

pnpm deploy:web

Wrangler 会先执行 vite build 生成 SSR 产物，再将产物发布到 Cloudflare Workers。

部署成功后，控制台会输出访问地址：

Deployed your-web-worker triggers:
https://your-web-worker.your-subdomain.workers.dev

验证部署

访问 Web Worker 地址，逐项确认：

首页正常加载
用户注册 / 登录（邮箱 + OAuth）
支付结账流程（需 Stripe 配置完成）
文件上传（需 R2 配置完成）

方式二：GitHub 自动部署

将 GitHub 仓库与 Cloudflare 绑定后，每次推送到指定分支都会自动触发构建和部署。

Web 端没有 Secrets，GitHub 自动部署配置比 Server 更简单——只需连接仓库和填写构建配置即可。

连接 GitHub 仓库

进入 Cloudflare Dashboard → Workers & Pages
点击 Create → Workers → Connect to Git
授权 Cloudflare 访问你的 GitHub 账户，选择对应仓库
选择部署分支（通常为 main）

填写构建配置

在构建设置页面填入以下配置：

项目	值
根目录	`/`
构建命令	`pnpm --filter web build`
部署命令	`pnpm --filter web run deploy`
版本命令	`pnpm --filter web run deploy`

根目录设置为 / 是因为这是 monorepo，pnpm workspace 需要从仓库根目录解析依赖。

配置完成后，每次向目标分支推送代码，Cloudflare 都会自动触发构建并部署最新版本。可在 Workers & Pages → 你的 Worker → Deployments 中查看每次部署的状态和日志。

自定义域名（推荐）

进入 Cloudflare Dashboard → Workers & Pages → 选择你的 Web Worker
进入 Settings → Domains & Routes
点击 Add Custom Domain，输入域名（需托管在 Cloudflare），例如 app.yourdomain.com
绑定成功后，按以下说明更新相关配置

为什么必须同步更新多处配置

VITE_APP_URL 和 VITE_SERVER_URL 写在 wrangler.jsonc 的 vars 中，随构建打包进 Worker Bundle。改了值必须重新部署才能生效。

同时，Server 端也引用了 WEBSITE_URL（Better Auth trusted origins），如果 Web 的域名变了，Server 侧也需要同步，否则认证请求会被 CORS 拦截。

需要修改的文件

apps/web/wrangler.jsonc

"vars": {
  "VITE_SERVER_URL": "https://api.yourdomain.com",  // 与 Server 自定义域名一致
  "VITE_APP_URL": "https://app.yourdomain.com"      // Web 新绑定的自定义域名
}

apps/server/wrangler.jsonc

"vars": {
  "WEBSITE_URL": "https://app.yourdomain.com",       // 同步更新为 Web 新域名
  "SERVER_URL": "https://api.yourdomain.com"
}

重新部署使配置生效

两边都有改动，同时部署：

pnpm deploy

等价于先执行 pnpm deploy:server，再执行 pnpm deploy:web。

vars 是静态配置，随代码打包。每次修改 wrangler.jsonc 的 vars，都必须重新部署才能生效。