Wasp 前端部署 Cloudflare Workers 实战：静态资源托管、SPA 回退与 GitHub Actions 自动发布

Wasp 前端部署 Cloudflare Workers 实战静态资源托管、SPA 回退与 GitHub Actions 自动发布【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/waspWasp 采用全栈声明式架构构建产物的客户端React 前端只是一批静态文件天然适合部署到免费且边缘分布的 Cloudflare Workers。本指南以仓库文档 cloudflare.md 为骨架完整讲解如何用 Wrangler 将 Wasp 客户端发布到 Workers、配置静态资源与 SPA 回退、打通WASP_WEB_CLIENT_URL服务器变量并通过 GitHub Actions 实现推送即部署的持续发布。读完你即可独立完成客户端上云 服务器对接 CI/CD 自动化的完整闭环。整体思路Wasp 应用的三个可部署部分从仓库文档 cloud-providers.md 可以看到一次生产部署由四件事组成用wasp build生成可部署代码部署 API 服务器后端需要支持 Node.js 与 PostgreSQL部署 Web 客户端前端只需静态托管部署并保持一个 PostgreSQL 数据库运行。本文聚焦第 3 步的 Cloudflare 实现把.wasp/out/web-app/build目录下的静态产物托管到 Cloudflare Workers。后端与数据库仍需按你选定的提供方如 Fly.io、Railway 或自托管另行部署部署完成后把客户端域名回填到服务器的WASP_WEB_CLIENT_URL环境变量即可打通全栈。前置准备登录 Wrangler 并构建 Wasp 应用1. 注册账号并使用 Wrangler 登录需要先拥有一个 Cloudflare 账号然后使用 Cloudflare 官方的命令行工具 Wrangler 登录npx wrangler login该命令会在浏览器中打开授权页面完成认证认证信息保存在本地 Wrangler 配置中后续npx wrangler deploy会直接复用。2. 先构建 Wasp 应用在继续之前必须先为整个应用生成可部署代码在项目根目录运行wasp build如 cloud-providers.md 所述wasp build会把全栈应用的可部署代码输出到.wasp/out/目录。:::caution 生产环境必须使用 PostgreSQL 如果项目仍在使用默认的 SQLite 数据库wasp build将无法完成构建。生产部署前必须先切换到 PostgreSQL迁移步骤参见 databases.md。 :::构建客户端 Web 应用Wasp 客户端是基于 Vite 构建的仓库的 _building-the-web-client.md 给出了标准的构建命令REACT_APP_API_URLurl_to_wasp_backend npx vite build其中url_to_wasp_backend是你已经部署好的 Wasp 服务器地址。构建完成后静态产物位于.wasp/out/web-app/build构建出的build目录中还包含一个200.html文件它位于目录根部作用正是单页应用SPA的路由回退文件——当用户直接访问/some/client/route这类客户端路由时由它兜底渲染。这也是下文 Worker 配置的核心依据。客户端环境变量必须在构建时注入在 env-vars.md 中有两条关键说明客户端环境变量如REACT_APP_API_URL是在构建阶段被注入到 JS 代码中的属于公开可读内容绝不能存放密钥.env.client文件在生产构建时会被忽略必须显式把生产环境变量追加到构建命令中例如REACT_APP_API_URLurl_to_wasp_backend REACT_APP_SOME_OTHER_VARsomevalue npx vite build原理上构建时 Wasp/Vite 会把客户端代码中的import.meta.env.REACT_APP_*替换为实际值。因此不要指望在 Cloudflare 面板上给静态客户端设置环境变量——静态文件是构建产物托管侧的变量对它无效。创建 wrangler.toml把 Worker 与静态资源绑定在项目根目录创建两个文件放在项目根可以保证它们被版本控制追踪。首先是wrangler.toml用于把 Worker 配置为静态资产托管模式name my-wasp-app-client main ./worker.js compatibility_date 2026-03-30 [assets] directory ./.wasp/out/web-app/build binding ASSETS字段说明nameWorker 名称同时决定了默认访问域名前缀https://my-wasp-app-client.subdomain.workers.dev可按需改名。main入口脚本路径指向下一步创建的worker.js。compatibility_dateWrangler/Workers 运行时的兼容性日期选择你使用的 Cloudflare Workers 运行时的兼容日期即可文档核对时点为 2026-04-06即用 2026-03-30 或更新的兼容日期。[assets]静态资源配置。directory指向.wasp/out/web-app/build也就是上一步 Vite 构建出的客户端产物目录binding将资源绑定到名为ASSETS的绑定上供worker.js通过env.ASSETS访问。编写 worker.js静态文件 SPA 回退在项目根目录创建worker.js实现命中静态文件则返回、未命中则回退到 SPA 外壳export default { async fetch(request, env) { // If the static asset is not found, return the SPA fallback. const spaFallbackUrl new URL(/200, request.url); const spaFallbackRequest new Request(spaFallbackUrl, request); return await env.ASSETS.fetch(spaFallbackRequest); }, };这段逻辑的关键在于当请求的资源CSS、JS、图片或已预渲染的 HTML 页面在静态目录中存在时env.ASSETS.fetch(request)会直接命中返回当请求落在客户端路由如/dashboard目录中不存在该文件时则改写请求路径为/200对应的200.html由 Wasp 的 SPA 外壳接管并渲染对应页面。这正是 cloud-providers.md 中所说的200.html 作为 SPA 回退在 Workers 上的落地实现。如果你的应用启用了预渲染prerendering预渲染产生的静态页面会优先被资产命中回退机制只兜底未预渲染的客户端路由。部署客户端一切就绪后在项目根目录执行npx wrangler deployWrangler 会上传worker.js与[assets]目录指向的静态产物创建并发布 Worker。完成后你的客户端即上线访问地址形如https://my-wasp-app-client.subdomain.workers.dev别忘了设置服务器端的 WASP_WEB_CLIENT_URL客户端上线后必须在服务器托管环境中把 Workers 域名设置为WASP_WEB_CLIENT_URL环境变量。这是 Wasp 服务器判断客户端在哪里的关键配置认证跳转、邮件链接、CORS 等依赖它的场景都会用到。参考 env-vars.md 中对服务器必需变量的说明WASP_WEB_CLIENT_URL与DATABASE_URL、WASP_SERVER_URL、JWT_SECRET等一样属于生产环境必须显式设置的服务器变量缺失会导致服务器启动失败。设置时注意按惯例带上https://前缀与 vercel.md 中对该变量的要求一致。通过 GitHub Actions 自动部署手动执行npx wrangler deploy可以完成首发布但更常见的是推送即部署。在仓库中创建.github/workflows/deploy.yaml文件名可改扩展名需保持.yaml/.ymlname: Deploy Client to Cloudflare on: push: branches: - main # Deploy on every push to the main branch jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout Code uses: actions/checkoutv5 - name: Setup Node.js id: setup-node uses: actions/setup-nodev5 with: node-version: {minimumNodeJsVersion} - name: Install Wasp run: npm i -g wasp.sh/wasp-cli{latestWaspVersion} # Change to your Wasp version - name: Install Wasp app dependencies run: cd ./app wasp install - name: Wasp Build run: cd ./app wasp build - name: Build the client run: cd ./app REACT_APP_API_URL${{ secrets.WASP_SERVER_URL }} npx vite build - name: Deploy to Cloudflare Workers uses: cloudflare/wrangler-actionv3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} workingDirectory: ./app command: deploy工作流要点触发条件仅在推送到main分支时触发构建链条wasp install安装依赖 →wasp build生成产物 → 以REACT_APP_API_URL${{ secrets.WASP_SERVER_URL }}重新构建客户端与手动构建命令一致保证注入正确的后端地址发布动作使用cloudflare/wrangler-actionv3通过 API Token 认证并在./app目录执行deploy即等价于手动运行npx wrangler deploy。若项目结构不是./app子目录请把各步的cd ./app调整为实际目录{minimumNodeJsVersion}与{latestWaspVersion}需替换为你的 Wasp 版本对应的 Node.js 最低版本与实际 Wasp CLI 版本号文档核对时对应 Wasp 0.24。三个必需的 GitHub Secrets在仓库Settings → Secrets and variables → Actions中配置以下密钥Secret说明CLOUDFLARE_API_TOKEN在 Cloudflare 控制台的 API 令牌页面创建必须授予Cloudflare Workers: Edit权限CLOUDFLARE_ACCOUNT_ID你的 Cloudflare 账户 ID与 Token 在同一页面可获取WASP_SERVER_URL后端服务器地址通常在部署完后端之后才有后端未就绪时该变量可先跳过但依赖后端的登录、查询等功能会暂时不可用把三个值都填好后每次推送main分支GitHub Actions 就会自动完成构建 → 重新打包客户端 → 发布到 Cloudflare Workers的全流程。更新与重新部署后续迭代时的标准操作与首次部署一致本地改动后运行wasp build重新生成产物在项目根目录重新执行REACT_APP_API_URLurl_to_wasp_backend npx vite build刷新.wasp/out/web-app/build再次运行npx wrangler deploy发布新版本。若已配置 GitHub Actions则上述过程完全由push自动接管无需手动操作。小结与适用边界至此Wasp 前端已经跑在 Cloudflare Workers 免费层上wrangler.toml负责静态资源绑定worker.js用/200回退兜住所有客户端路由WASP_WEB_CLIENT_URL打通前后端GitHub Actions 完成持续交付。需要留意的是本文方案只托管客户端后端仍需要一个支持 Node.js 与 PostgreSQL 的服务Wasp 的服务器不能在纯静态的 Workers 上运行且涉及 OAuth 等外部认证配置时还需按 env-vars.md 的要求在服务器环境补齐对应变量。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考