Wasp 应用 CI/CD 实战指南用 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/wasp本指南围绕 Wasp 官方部署文档中的 CI/CD 章节展开讲解如何在 Wasp 全栈项目中搭建持续集成CI与持续部署CD流水线在代码推送时自动运行 Playwright 端到端测试与 Vitest 单元测试再通过 Docker 镜像或静态文件两种方式将应用自动发布到生产环境。读完本文你将掌握完整的 GitHub Actions 工作流编写方法、Wasp 构建产物结构以及仓库内真实 CI 配置的参考实现。理解 CI/CD为什么 Wasp 应用需要自动化流水线持续集成Continuous IntegrationCI是指在代码推送到仓库时通过自动化流程验证和测试代码变更的过程。它帮助团队尽早发现 bug、确认应用仍然可用避免本地能跑、合并后崩了的回归问题。持续部署Continuous DeploymentCD则指代码变更被自动部署到生产环境的过程也就是常说的push to deploy。它把开发者从手动部署中解放出来让每一次通过验证的提交都能稳定地到达用户手中。对 Wasp 应用而言由于wasp build会一次性产出后端 Node.js 服务与前端 React 应用详见 生成可部署代码CI/CD 流水线恰好可以把测试 构建 发布串联为一条自动化链路。在 CI 中运行端到端e2e测试端到端测试模拟真实用户使用应用的过程可以覆盖登录、添加任务、购物车结算等完整业务场景。写好 e2e 测试后你就不必在每次改动后手动回归一遍应用。在 CI 中运行 e2e 测试的三个步骤官方文档给出了一套通用流程在 CI 环境中安装 Wasp运行你的应用连同数据库对运行中的应用执行 e2e 测试。第二步是关键e2e 测试需要一个真实在跑的服务端与前端因此 CI 作业里必须先把应用启动起来通常用wasp start或wasp build后的产物启动再让测试框架访问它。编写 Playwright e2e 测试官方推荐使用 Playwright 作为 e2e 测试框架。以下是文档中给出的一个基础用户流程测试示例import { expect, test } from playwright/test import { generateRandomUser, logUserIn } from ./utils const user generateRandomUser() test.describe(basic user flow test, () { test(log in and add task, async ({ page }) { await logUserIn({ page, user }) await expect(page).toHaveURL(/) await expect(page.locator(body)).toContainText(No tasks yet.) // Add a task await page.fill(input[namedescription], First task) await page.click(input:has-text(Create task)) await expect(page.locator(body)).toContainText(First task) }) })这段测试覆盖了注册/登录 → 进入首页 → 断言初始空状态 → 创建任务 → 断言新任务出现在页面上的完整链路generateRandomUser保证每次运行使用随机用户避免测试数据冲突。如果你想在本地先跑通这套流程可以复制仓库中示例项目的e2e-tests目录例如 ask-the-documents 的 e2e-tests按自己的应用场景修改后使用。仓库中的真实 Playwright 配置剖析仓库中多个示例项目都带有一套成熟的 Playwright 配置以 examples/ask-the-documents/e2e-tests/playwright.config.ts 为例它展示了大量面向 CI 环境的细节CI 下禁止残留test.only第 22 行forbidOnly: !!process.env.CI防止开发调试用的聚焦测试被误提交进 CICI 下自动重试 2 次第 24 行retries: process.env.CI ? 2 : 0缓解网络抖动等不稳定因素CI 下串行执行第 26 行workers: process.env.CI ? 1 : undefined避免多个测试进程争抢同一个后端CI 下使用精简报告器第 28 行reporter: process.env.CI ? dot : list内置 webServer 启动逻辑第 51-59 行通过webServer.command在测试前拉起应用与数据库该示例使用 pgvector 的 Postgres 镜像并等待http://localhost:3001后端就绪本地开发时非 CI则复用已存在的服务以加速迭代。这套配置可以直接作为你项目 CI 中运行应用这一步的参考实现。创建 GitHub Actions 工作流在 CI 中执行上述流程需要在仓库中新建一个工作流文件.github/workflows/e2e-tests.yml其骨架如下可参考官方 e2e 测试示例仓库的对应文件name: E2E Tests on: push: branches: [main] pull_request: jobs: e2e: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 - name: Install Wasp run: npm i -g wasp.sh/wasp-cli你的Wasp版本 - name: Install app dependencies run: wasp install - name: Run the app and e2e tests run: npx playwright test env: # 依据你的应用配置注入数据库连接等环境变量 DATABASE_URL: ${{ secrets.DATABASE_URL }}其中安装 Wasp对应流程第一步启动应用 执行测试由 Playwright 的webServer机制合并完成对应第二、三步。仓库自己的 CI 实现一份可直接借鉴的参考Wasp 仓库本身就在 GitHub Actions 中实践这套流程.github/workflows/ci-examples-test.yaml 是一个很有参考价值的真实实现使用matrix 矩阵对tutorials/TodoApp、waspello、waspleau、ask-the-documents、kitchen-sink等全部示例应用并行执行测试第 15-23 行依次执行wasp-cli install、wasp-cli compile生成 Wasp 库与wasp-cli test client run --passWithNoTests运行客户端单元测试第 42-44 行通过 scripts/get-wasp-database-provider.sh 探测数据库提供方对 SQLite 项目跳过 build 模式的 e2e 测试第 72-80 行因为 Wasp 生产构建不支持 SQLite借助仓库内的 wasp-app-runner 工具分别以dev和build两种模式拉起应用并执行 Playwright 测试。这印证了官方文档的流程安装 Wasp → 运行应用含数据库→ 跑测试同时给出了生产构建模式下 e2e 测试的可行方案。在 CI 中运行单元测试单元测试对代码逻辑做隔离验证比 e2e 测试更快、更简单但不模拟真实用户交互。Wasp 为前端代码内置了测试支持服务端则可选用任意测试框架。客户端单元测试Vitest 与测试助手Wasp 前端基于 Vite因此通过 Vitest 提供单元测试与 React 组件测试能力详见 Testing。在 CI 中只需执行wasp test client runwasp test client会启动 Vitest 监听模式并在代码变化时重编译run子命令则表示只运行一次后退出正是 CI 环境需要的模式。注意wasp test与wasp start不能同时运行因为两者都会向.wasp/out写入编译产物。测试文件需放在src目录内并使用*.test.ts、*.spec.jsx等 Vitest 可识别的命名。Wasp 还提供了两个开箱即用的测试助手从wasp/client/test导入renderInContext把组件包进QueryClientProvider和Router后渲染用于组件测试mockServer/mockQuery/mockApi基于 msw 搭建模拟服务器mock 掉 Wasp 查询与自定义 API让组件测试不依赖真实后端。import { mockServer, renderInContext } from wasp/client/test; import { getTasks } from wasp/client/operations; const { mockQuery } mockServer(); test(handles mock data, async () { mockQuery(getTasks, mockTasks); renderInContext(Todo /); await screen.findByText(test todo 1); });服务端测试与 CI 单元测试小结文档指出服务端目前没有 Wasp 内置测试方案可自由选用 Jest、Vitest 等任意框架在 CI 中独立成 job 运行即可。整体而言单元测试在 CI 中的执行方式与 e2e 测试类似安装 Wasp → 运行wasp test client run→ 用你的框架运行服务端测试。持续部署两种主流发布方式CI/CD 流水线的部署环节官方文档给出了两条路线用 Docker 打包服务端与客户端把客户端作为静态文件部署。方式一Docker 镜像打包部署这是最常用的打包方式把应用构建成 Docker 镜像即可在 staging、production 等不同环境间复用同一份产物。完整的 CD 流程为在 CD 环境安装 Docker执行wasp install安装依赖、wasp build构建应用分别构建服务端镜像与客户端镜像推送到 Docker Registry对部分平台通过 Webhook 等机制通知其拉取并部署新版本。什么是 Docker RegistryDocker Registry 是存放 Docker 镜像的仓库部署平台从这里拉取镜像。最常用的是 Docker Hub也可以使用 GitHub Container RegistryGHCR等私有/公开注册中心。Coolify 部署示例一份完整的 deploy.yml官方文档以 Coolify 自托管平台为例展示了完整的 GitHub Actions 部署流水线。完整的 YAML 内容可在 Coolify 部署指南 中查看这里拆解其六个关键环节认证 GHCR使用docker/login-action以GITHUB_TOKEN作为密码登录容器注册中心准备镜像元数据使用docker/metadata-action为服务端、客户端镜像分别生成 tags 与 labels安装依赖并构建npm i -g wasp.sh/wasp-cli版本安装 Wasp随后wasp installwasp build产物输出到.wasp/out目录打包并推送服务端镜像使用.wasp/out内由 Wasp 生成的Dockerfile经docker/build-push-action构建并推送打包并推送客户端镜像在.wasp/out/web-app下生成一个基于 Go 静态服务器如pierrezemb/gostatic的Dockerfile将npx vite build产出的build目录打进镜像同样推送Webhook 通知 Coolify用curl携带 Bearer Token 调用服务端与客户端的部署 Webhook触发拉取新镜像。该工作流还在env中集中定义了SERVER_APP_NAME、CLIENT_APP_NAME、DOCKER_REGISTRY等变量并配置了concurrency分组保证同一时刻只有一个部署任务在跑。读者可打开 coolify.md 查看带完整注释的源码级示例。方式二静态部署客户端Wasp 的客户端是一个单页应用SPAwasp build后会被编译为静态 HTML、CSS、JS 文件可以上传到任何支持静态托管的平台。相比 Docker 镜像静态托管通常更便宜因此客户端不一定需要走 Docker。静态部署流程为在 CD 环境执行wasp install与wasp build执行npx vite build构建客户端把.wasp/out/web-app/build目录下的文件上传到托管平台。构建客户端时需要把后端地址通过环境变量传入见 构建 Web 客户端REACT_APP_API_URL你已部署的Wasp后端地址 npx vite build构建产物中会包含200.html它作为 SPA 路由回退文件保证前端路由在刷新时也能正确返回页面详见 云平台部署总览。Netlify 示例GitHub Actions 自动发布静态客户端以 Netlify 为例完整步骤见 Netlify 部署指南先在项目根目录创建netlify.toml声明发布目录并配置 SPA 回退规则[build] publish ./.wasp/out/web-app/build # 默认情况下Netlify 只在路径不匹配现有文件时重定向 [[redirects]] from /* to /200.html status 200随后在 GitHub Actions 中按安装 Wasp →wasp install→wasp build→ 带REACT_APP_API_URL执行npx vite build→netlify-cli deploy --prod --filter wasp --no-build的顺序编排即可实现每次推送main分支自动发布。其中--filter wasp用于在 Wasp 生成的 npm workspaces 中显式选中客户端包--no-build则避免 Netlify 重复构建。需要配置的仓库 Secrets 包括NETLIFY_AUTH_TOKEN、NETLIFY_SITE_ID与WASP_SERVER_URL。Cloudflare 的部署方式与之类似可参考 Cloudflare 部署指南。部署环境变量与注意事项无论采用哪种部署方式都需要为生产环境正确配置服务端环境变量详见 部署环境变量变量说明DATABASE_URLPostgreSQL 连接串生产环境必须使用 PostgreSQLWasp 生产构建不支持 SQLiteJWT_SECRET至少 32 字符的随机字符串用于签名会话令牌PORT服务端监听端口如3001WASP_WEB_CLIENT_URL客户端对外地址如https://myapp.comWASP_SERVER_URL服务端对外地址如https://api.myapp.comREACT_APP_API_URL构建客户端时注入的后端地址几个容易踩坑的点SQLite 无法生产构建若项目仍使用默认的 SQLite需先迁移到 PostgreSQL 再进入部署环节客户端环境变量在构建时固化REACT_APP_API_URL等客户端变量在vite build时就被内联进产物改后端地址必须重新构建客户端测试与开发不能并行wasp test与wasp start会同时写.wasp/out不要在本地同时运行CI 稳定性参考仓库的 playwright.config.ts通过CI环境变量切换重试次数、串行执行与报告格式可显著提升流水线稳定性。小结本文从 Wasp 官方 CI/CD 文档出发完整覆盖了两条主线CI 侧用三步流程安装 Wasp → 运行应用与数据库 → 执行测试把 Playwright e2e 测试和 Vitest 单元测试接入 GitHub Actions并以仓库真实配置ci-examples-test.yaml、playwright.config.ts作为参考实现CD 侧对比了 Docker 镜像打包含完整的 Coolify 工作流与静态客户端部署含 Netlify 工作流两条路径。结合.wasp/out构建产物的结构与部署环境变量清单你现在可以动手为 Wasp 应用搭建一条推送即测试、通过即上线的完整流水线。【免费下载链接】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），仅供参考