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部署是应用从本地开发走向线上访问的最后一公里。本文以 Wasp 官方部署文档为核心完整讲解 Wasp 应用的组成部分与部署原理涵盖生产环境变量、PostgreSQL 数据库与迁移、wasp build与wasp build start本地生产预演、CI/CD 流水线、云端与自托管部署路径以及自定义域名与 CDN 等上线细节。读完本文你将能独立完成从本地wasp start到生产环境可访问的完整部署闭环。Wasp 应用的三组件架构在动手部署之前需要先理解 Wasp 构建产物到底由哪几部分组成。在 部署总览文档 中Wasp 应用被明确拆分为三个相互独立的部分客户端应用Client app一个基于 React 构建的单页应用SPA是用户看到并与之交互的部分。它通常由静态文件服务器提供服务或托管在 Cloudflare、Netlify 等 CDN 上。服务端应用Server app基于 Node.js 上的 Express 框架构建的后端。它处理来自客户端的请求、与数据库交互并返回响应。Wasp 会为服务端生成一份开箱即用的Dockerfile方便你在任何支持 Docker 的环境中打包部署。数据库DatabaseWasp 生产环境使用 PostgreSQL。数据库可以托管在自有服务器上也可以使用云托管服务。关键认知在于客户端应用与服务端应用是两个独立的应用程序通过 HTTP 协议互相通信。这意味着你可以按需把它们部署在同一台服务器上也可以部署在不同的服务器上——这种松耦合设计是后续所有部署方式的基础。从源码角度看服务端应用的运行方式在生成模板中有直接体现waspc/data/Generator/templates/Dockerfile 中定义了server-production阶段其入口为ENTRYPOINT [npm, run, start-production]而 waspc/data/Generator/templates/server/package.json 中声明了start-production脚本。也就是说生产环境服务端启动时会自动执行迁移等准备工作详见下文数据库与迁移小节。部署前必读生产环境变量开发阶段我们依赖.env.client与.env.server文件管理环境变量但部署时这些文件会被完全忽略必须通过其他方式提供环境变量。这是最容易踩坑的地方之一环境变量部署文档 对此有专门说明。客户端环境变量Client Env Vars客户端环境变量在构建过程中被注入客户端 JavaScript 代码因此对任何人都公开可读绝不能存放密钥如 API 密钥。生产构建时.env.client会被忽略你需要直接把生产客户端环境变量传给构建命令REACT_APP_API_URLurl_to_wasp_backend REACT_APP_SOME_OTHER_VAR_NAMEsomeothervalue npx vite build其底层原理是Wasp 在构建过程中会把客户端代码中所有import.meta.env.REACT_APP_SOME_VAR_NAME替换为实际提供的值注入到静态文件中。因此构建时若缺少必需的客户端环境变量构建会失败请对照 项目环境变量文档 中的客户端通用配置逐项核对不要试图在托管平台上为客户端设置环境变量——客户端此时只是静态文件会忽略这些设置。服务端环境变量Server Env Vars生产构建时.env.server同样被忽略服务端环境变量需要定义在运行服务端代码的机器上通过托管平台提供的机制注入。# 以 Fly.io 为例使用 fly CLI 设置 fly secrets set SOME_VAR_NAMEsomevalue需要特别注意的是以下服务端通用环境变量它们在开发环境无需设置但生产环境必须显式配置缺失会导致服务端启动失败DATABASE_URL数据库连接串WASP_WEB_CLIENT_URL客户端应用域名WASP_SERVER_URL服务端域名PORT服务端监听端口如果你使用 Wasp CLI 的wasp deploy方式部署Wasp 会自动帮你设置这些通用配置变量但其余变量如 OAuth 认证方法相关变量、自定义变量仍需自行配置。用wasp build start做上线前的最后检查wasp build start是验证生产构建能否正常工作的利器它读取wasp build的输出在本地启动一个服务器来运行生产代码并强制你显式指定所有需要的环境变量——这能帮你提前发现依赖本地.env文件的隐患以及只在生产模式React dev mode、hot reload 等特性被关闭下才暴露的问题。# 启动本地数据库复制连接 URL wasp start db # 启动本地生产构建服务器示例实际可能需要更多环境变量 wasp build start --server-env DATABASE_URLyour-database-url --server-env JWT_SECRETyour-jwt-secret该命令支持--server-env、--client-env逐项传值也支持--server-env-file、--client-env-file指向环境变量文件如wasp build start --server-env-file .env.staging --client-env-file .env.client.staging。唯一的例外是PORT、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、REACT_APP_API_URL这类端口与 URL 配置——wasp build start知道你是在本地运行会自动填写手动设置反而会导致命令失败如需自定义端口请使用--client-port和--server-port。wasp build start与wasp start的核心差异如下方面wasp startwasp build start用途本地开发本地生产测试非正式部署命令服务端环境Node.jsDocker 容器中的 Node.js客户端环境静态服务器静态服务器资源逐个独立提供打包并压缩React dev mode开启关闭热重载开启关闭Source maps开启关闭调试支持完整有限性能较慢正常注意测试时应使用 staging/沙箱凭据如 Stripe 测试密钥、隔离的本地数据库并保持与生产环境的配置一致性功能开关、回调/重定向 URL 等切勿使用真实生产密钥。数据库与迁移生产库的配置与维护本地开发时我们用wasp start db启动开发数据库上线时则需要配置生产数据库。数据库部署文档 说明Wasp 生成的服务器唯一硬性要求是数据库可通过DATABASE_URL服务端环境变量从服务器访问。它可以与服务器同机运行也可以是 Fly Postgres、AWS RDS 等托管服务。PostgreSQL 各主要版本行为可能不同开发与生产最好使用相同的大版本。迁移的创建与应用每当修改 Prisma schemaprisma 文件说明例如新增模型、修改字段类型都需要创建迁移wasp db migrate-dev该命令会在migrations目录下生成一组描述 schema 变更的 SQL 命令。迁移的应用方式在开发与生产环境不同开发环境运行wasp start时自动应用生产环境服务端应用启动前会先检查是否存在待应用的迁移有则先应用再启动服务器从而保证数据库 schema 与 Prisma schema 始终同步。这一机制在生成代码中有明确体现正如上文所述生产 Docker 镜像的入口是npm run start-production见 Dockerfile 模板 与 server/package.json 中的start-production脚本该脚本会在启动服务器前先应用所有待执行的迁移。迁移失败如何排查如果迁移与应用中已有数据冲突例如对已含重复值的字段添加unique约束迁移会失败服务端记录错误日志后停止。此时应连接生产数据库排查可在_prisma_migrations表中看到失败的迁移记录。典型处理流程清除数据库中的重复数据从_prisma_migrations表中删除失败的迁移记录重启服务端应用重新应用迁移。注意wasp db studio无法查看生产库的_prisma_migrations表需要使用 DBeaver、pgAdmin 等数据库管理工具。连接生产数据库排查数据开发环境用wasp db studio打开基于 Web 的数据库管理工具要查看生产库只需在终端中设置DATABASE_URL指向生产库后再运行DATABASE_URLpostgresql://user:passwordhost:port/dbname wasp db studio强烈建议通过终端环境变量方式传入而非写入.env.server——否则你可能忘记移除它导致本地wasp start时误操作生产数据库。连接 Fly.io 生产库的具体做法可参考 Fly.io 数据库 Studio 指南。构建可部署产物wasp build无论采用哪种部署方式第一步都是把 Wasp 应用构建为可部署的代码。运行以下命令wasp build构建产物生成在.wasp/out/目录其中包括服务端应用.wasp/out中有一份用于构建服务端镜像的Dockerfile客户端应用.wasp/out/web-app/build目录包含静态 HTML/CSS/JS 文件根部还有200.html作为 SPA 回退文件。构建客户端静态文件的命令为REACT_APP_API_URLurl_to_wasp_backend npx vite build其中url_to_wasp_backend是你已部署的 Wasp 服务端 URL。重要限制如果使用 SQLite默认数据库将无法完成生产构建。部署前必须先从 SQLite 迁移到 PostgreSQL。完整的云端手工部署四步流程是生成可部署代码wasp build→ 部署 API 服务器后端→ 部署 Web 客户端前端→ 部署并维护 PostgreSQL 数据库详见 云端部署文档。部署方式全景CLI 一键部署、云端与自托管Wasp Deploy一条命令完成部署Wasp CLI 提供一键式全栈部署是官方推荐的部署方式见 Wasp Deploy 总览wasp deploy provider launch my-wasp-app该命令会自动在提供商侧创建所需服务、构建 Wasp 应用并完成部署。目前支持 Fly.io、Railway 等提供商各平台的详细步骤参见 Fly.io 部署指南 与 Railway 部署指南。云端提供商部署只要提供商支持运行 Node.js 服务器、提供静态文件服务并支持 PostgreSQL就能部署 Wasp 应用。仓库文档提供了 Vercel、Cloudflare Workers、Fly.io、Heroku、Netlify、Railway、Render 等平台的逐步指南见 云端部署总览 及各指南目录 web/docs/guides/deployment/cloud-providers。自托管部署拥有自有服务器或租用 VPS时可以自托管获得对应用和数据的完全控制也便于在单台服务器上部署多个应用以降低成本代价是需要自己维护服务器。自托管部署文档 给出的一般流程为从应用代码构建服务端应用与客户端应用在服务器上设置服务端环境变量在服务器上运行数据库或使用托管数据库服务运行服务端应用可用 Docker也可不用用静态文件服务器托管客户端应用设置反向代理Nginx、Caddy、Traefik 等使应用可通过域名 HTTPS 访问。推荐的域名规划是客户端用myapp.com、服务端用api.myapp.com反向代理在myapp.com上托管客户端静态文件并把 API 请求代理到服务端应用同时确保 环境变量 使用这些域名。自托管时的数据库运维需要自行负责备份、升级与扩缩容建议为 PostgreSQL 配置定期备份和/或服务器磁盘快照若不想自运维可选择 AWS RDS、DigitalOcean Managed Databases、Supabase 等托管服务。仓库还提供了 CapRover、Coolify、纯 DockerUbuntu Git Caddy等具体自托管指南见 web/docs/guides/deployment/self-hosted。自定义 Dockerfile 钩子Wasp 默认生成多阶段 Dockerfile用于构建并运行服务端镜像同时会执行待应用的迁移。你可以在项目根目录创建自己的DockerfileWasp 检测到后会把其内容追加到默认多阶段 Dockerfile 的底部——由于 Dockerfile 中最后定义者生效你可以覆盖或延续任意构建阶段甚至可以完全不用 Wasp 的构建阶段而让自定义 Dockerfile 原样生效。需要注意若覆盖了中间构建阶段后续阶段将不再使用除非你在下方自行重现生成的 Dockerfile 内容随应用功能动态变化且未来版本可能变动请定期核实最终构建阶段必须提供ENTRYPOINT否则你的改动不会生效。想查看项目最终可能已合并的Dockerfile 内容可运行wasp dockerfileCI/CD让部署自动化为应用配置 CI/CD 流水线是强烈推荐的实践。CI/CD 文档 将其分为两部分CI持续集成在代码推送时自动验证/测试代码及早发现 bugCD持续部署将代码变更自动部署到生产环境即push to deploy。在 CI 中运行测试端到端e2e测试模拟真实用户操作登录、加入购物车等在 CI 中运行的步骤为①在 CI 环境安装 Wasp②在 CI 环境运行应用含数据库③对运行中的应用执行 e2e 测试。仓库示例应用examples/ask-the-documents、examples/kitchen-sink 等均带有 Playwright e2e 测试目录与playwright.config.ts配置可作参考。典型 e2e 测试用例Playwrightimport { 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) }) })单元测试更简单快速但无法模拟真实用户交互。Wasp 内置客户端测试支持wasp test client run服务端可选用任意测试框架项目测试文档 有详细说明。持续部署的两条路径路径一用 Docker 打包服务端与客户端。这是最常用的方式同一镜像可轻松部署到 staging、production 等不同环境。流程为①在 CD 环境安装 Docker②wasp install安装依赖并用wasp build构建③构建并推送服务端、客户端的 Docker 镜像到镜像仓库如 Docker Hub、GHCR④对部分提供商通过 Webhook 通知其部署新版本。路径二客户端作为静态文件部署。客户端是 SPA构建产物只是静态 HTML/CSS/JS可直接上传到任意静态托管商通常比托管 Docker 镜像更便宜。流程为①在 CD 环境wasp installwasp build②npx vite build构建客户端③将.wasp/out/web-app/build中的静态文件上传到托管商。上线后的进阶配置自定义域名、CDN 与生产就绪性自定义域名客户端与服务器都可配置自定义域名其中客户端域名是用户浏览器访问的入口更为关键服务器域名则用于隐藏 IP 地址或自动生成域名等细节。设置过程分两步配置 DNS 记录在 DNS 设置中添加指向应用 IPv4 地址的A记录通常同时配置 IPv6 的AAAA记录部分提供商要求用CNAME记录替代。使用wasp deploy时可参考 Fly.io 自定义域名 或 Railway 自定义域名。设置环境变量构建客户端时设置REACT_APP_API_URL指向服务器域名如REACT_APP_API_URLhttps://api.myapp.com服务器侧配置两个变量——WASP_WEB_CLIENT_URLhttps://myapp.com与WASP_SERVER_URLhttps://server.myapp.com以保证 CORS 等行为正确。CDN 与 DDoS 防护在生产环境可考虑使用 CDN 与 DDoS 防护服务CDN全球分布的缓存服务器网络缓存图片、CSS、JS 等静态资源。在客户端前放置 CDN 可加速全球用户的资源加载就近服务。若客户端也通过自定义域名服务REACT_APP_API_URL应指向服务器域名。DDoS 防护攻击者以大量流量压垮服务器使其无法服务合法用户。可为客户端与服务器同时启用 DDoS 防护服务。文档推荐使用 Cloudflare 同时承担 CDN 与 DDoS 防护免费额度对大多数中小型应用足够Fastly、Bunny、Amazon CloudFront 等也是可选方案。Wasp 应用的生产就绪性回到开头提到的三组件架构Wasp 应用由 Node.js Express 服务端、PostgreSQL 数据库、React Vite 客户端组成每一部分本身都是久经考验的生产级组件Wasp 只是让它们更容易连接在一起。同时需要留意Wasp 目前仍处于 beta 阶段可能存在个别粗糙之处部署前建议用wasp build start做好本地预演并按上文清单逐项核对环境变量与数据库配置。总结部署 Wasp 应用的本质是把客户端 SPA Express 服务端 PostgreSQL 数据库这三个独立组件分别交付到生产环境并通过环境变量与 HTTP 通信将它们串联起来。掌握了wasp build产物结构、生产环境变量规则、迁移机制、wasp build start本地预演以及一键部署、云端、自托管、CI/CD 等不同路径后你就可以根据自己的基础设施与预算选择最合适的上线方案。相关文档均可在仓库的 web/docs/deployment 目录下继续深入查阅。【免费下载链接】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），仅供参考
Wasp 应用部署完全指南：理解三组件架构并打通生产环境上线全流程
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部署是应用从本地开发走向线上访问的最后一公里。本文以 Wasp 官方部署文档为核心完整讲解 Wasp 应用的组成部分与部署原理涵盖生产环境变量、PostgreSQL 数据库与迁移、wasp build与wasp build start本地生产预演、CI/CD 流水线、云端与自托管部署路径以及自定义域名与 CDN 等上线细节。读完本文你将能独立完成从本地wasp start到生产环境可访问的完整部署闭环。Wasp 应用的三组件架构在动手部署之前需要先理解 Wasp 构建产物到底由哪几部分组成。在 部署总览文档 中Wasp 应用被明确拆分为三个相互独立的部分客户端应用Client app一个基于 React 构建的单页应用SPA是用户看到并与之交互的部分。它通常由静态文件服务器提供服务或托管在 Cloudflare、Netlify 等 CDN 上。服务端应用Server app基于 Node.js 上的 Express 框架构建的后端。它处理来自客户端的请求、与数据库交互并返回响应。Wasp 会为服务端生成一份开箱即用的Dockerfile方便你在任何支持 Docker 的环境中打包部署。数据库DatabaseWasp 生产环境使用 PostgreSQL。数据库可以托管在自有服务器上也可以使用云托管服务。关键认知在于客户端应用与服务端应用是两个独立的应用程序通过 HTTP 协议互相通信。这意味着你可以按需把它们部署在同一台服务器上也可以部署在不同的服务器上——这种松耦合设计是后续所有部署方式的基础。从源码角度看服务端应用的运行方式在生成模板中有直接体现waspc/data/Generator/templates/Dockerfile 中定义了server-production阶段其入口为ENTRYPOINT [npm, run, start-production]而 waspc/data/Generator/templates/server/package.json 中声明了start-production脚本。也就是说生产环境服务端启动时会自动执行迁移等准备工作详见下文数据库与迁移小节。部署前必读生产环境变量开发阶段我们依赖.env.client与.env.server文件管理环境变量但部署时这些文件会被完全忽略必须通过其他方式提供环境变量。这是最容易踩坑的地方之一环境变量部署文档 对此有专门说明。客户端环境变量Client Env Vars客户端环境变量在构建过程中被注入客户端 JavaScript 代码因此对任何人都公开可读绝不能存放密钥如 API 密钥。生产构建时.env.client会被忽略你需要直接把生产客户端环境变量传给构建命令REACT_APP_API_URLurl_to_wasp_backend REACT_APP_SOME_OTHER_VAR_NAMEsomeothervalue npx vite build其底层原理是Wasp 在构建过程中会把客户端代码中所有import.meta.env.REACT_APP_SOME_VAR_NAME替换为实际提供的值注入到静态文件中。因此构建时若缺少必需的客户端环境变量构建会失败请对照 项目环境变量文档 中的客户端通用配置逐项核对不要试图在托管平台上为客户端设置环境变量——客户端此时只是静态文件会忽略这些设置。服务端环境变量Server Env Vars生产构建时.env.server同样被忽略服务端环境变量需要定义在运行服务端代码的机器上通过托管平台提供的机制注入。# 以 Fly.io 为例使用 fly CLI 设置 fly secrets set SOME_VAR_NAMEsomevalue需要特别注意的是以下服务端通用环境变量它们在开发环境无需设置但生产环境必须显式配置缺失会导致服务端启动失败DATABASE_URL数据库连接串WASP_WEB_CLIENT_URL客户端应用域名WASP_SERVER_URL服务端域名PORT服务端监听端口如果你使用 Wasp CLI 的wasp deploy方式部署Wasp 会自动帮你设置这些通用配置变量但其余变量如 OAuth 认证方法相关变量、自定义变量仍需自行配置。用wasp build start做上线前的最后检查wasp build start是验证生产构建能否正常工作的利器它读取wasp build的输出在本地启动一个服务器来运行生产代码并强制你显式指定所有需要的环境变量——这能帮你提前发现依赖本地.env文件的隐患以及只在生产模式React dev mode、hot reload 等特性被关闭下才暴露的问题。# 启动本地数据库复制连接 URL wasp start db # 启动本地生产构建服务器示例实际可能需要更多环境变量 wasp build start --server-env DATABASE_URLyour-database-url --server-env JWT_SECRETyour-jwt-secret该命令支持--server-env、--client-env逐项传值也支持--server-env-file、--client-env-file指向环境变量文件如wasp build start --server-env-file .env.staging --client-env-file .env.client.staging。唯一的例外是PORT、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、REACT_APP_API_URL这类端口与 URL 配置——wasp build start知道你是在本地运行会自动填写手动设置反而会导致命令失败如需自定义端口请使用--client-port和--server-port。wasp build start与wasp start的核心差异如下方面wasp startwasp build start用途本地开发本地生产测试非正式部署命令服务端环境Node.jsDocker 容器中的 Node.js客户端环境静态服务器静态服务器资源逐个独立提供打包并压缩React dev mode开启关闭热重载开启关闭Source maps开启关闭调试支持完整有限性能较慢正常注意测试时应使用 staging/沙箱凭据如 Stripe 测试密钥、隔离的本地数据库并保持与生产环境的配置一致性功能开关、回调/重定向 URL 等切勿使用真实生产密钥。数据库与迁移生产库的配置与维护本地开发时我们用wasp start db启动开发数据库上线时则需要配置生产数据库。数据库部署文档 说明Wasp 生成的服务器唯一硬性要求是数据库可通过DATABASE_URL服务端环境变量从服务器访问。它可以与服务器同机运行也可以是 Fly Postgres、AWS RDS 等托管服务。PostgreSQL 各主要版本行为可能不同开发与生产最好使用相同的大版本。迁移的创建与应用每当修改 Prisma schemaprisma 文件说明例如新增模型、修改字段类型都需要创建迁移wasp db migrate-dev该命令会在migrations目录下生成一组描述 schema 变更的 SQL 命令。迁移的应用方式在开发与生产环境不同开发环境运行wasp start时自动应用生产环境服务端应用启动前会先检查是否存在待应用的迁移有则先应用再启动服务器从而保证数据库 schema 与 Prisma schema 始终同步。这一机制在生成代码中有明确体现正如上文所述生产 Docker 镜像的入口是npm run start-production见 Dockerfile 模板 与 server/package.json 中的start-production脚本该脚本会在启动服务器前先应用所有待执行的迁移。迁移失败如何排查如果迁移与应用中已有数据冲突例如对已含重复值的字段添加unique约束迁移会失败服务端记录错误日志后停止。此时应连接生产数据库排查可在_prisma_migrations表中看到失败的迁移记录。典型处理流程清除数据库中的重复数据从_prisma_migrations表中删除失败的迁移记录重启服务端应用重新应用迁移。注意wasp db studio无法查看生产库的_prisma_migrations表需要使用 DBeaver、pgAdmin 等数据库管理工具。连接生产数据库排查数据开发环境用wasp db studio打开基于 Web 的数据库管理工具要查看生产库只需在终端中设置DATABASE_URL指向生产库后再运行DATABASE_URLpostgresql://user:passwordhost:port/dbname wasp db studio强烈建议通过终端环境变量方式传入而非写入.env.server——否则你可能忘记移除它导致本地wasp start时误操作生产数据库。连接 Fly.io 生产库的具体做法可参考 Fly.io 数据库 Studio 指南。构建可部署产物wasp build无论采用哪种部署方式第一步都是把 Wasp 应用构建为可部署的代码。运行以下命令wasp build构建产物生成在.wasp/out/目录其中包括服务端应用.wasp/out中有一份用于构建服务端镜像的Dockerfile客户端应用.wasp/out/web-app/build目录包含静态 HTML/CSS/JS 文件根部还有200.html作为 SPA 回退文件。构建客户端静态文件的命令为REACT_APP_API_URLurl_to_wasp_backend npx vite build其中url_to_wasp_backend是你已部署的 Wasp 服务端 URL。重要限制如果使用 SQLite默认数据库将无法完成生产构建。部署前必须先从 SQLite 迁移到 PostgreSQL。完整的云端手工部署四步流程是生成可部署代码wasp build→ 部署 API 服务器后端→ 部署 Web 客户端前端→ 部署并维护 PostgreSQL 数据库详见 云端部署文档。部署方式全景CLI 一键部署、云端与自托管Wasp Deploy一条命令完成部署Wasp CLI 提供一键式全栈部署是官方推荐的部署方式见 Wasp Deploy 总览wasp deploy provider launch my-wasp-app该命令会自动在提供商侧创建所需服务、构建 Wasp 应用并完成部署。目前支持 Fly.io、Railway 等提供商各平台的详细步骤参见 Fly.io 部署指南 与 Railway 部署指南。云端提供商部署只要提供商支持运行 Node.js 服务器、提供静态文件服务并支持 PostgreSQL就能部署 Wasp 应用。仓库文档提供了 Vercel、Cloudflare Workers、Fly.io、Heroku、Netlify、Railway、Render 等平台的逐步指南见 云端部署总览 及各指南目录 web/docs/guides/deployment/cloud-providers。自托管部署拥有自有服务器或租用 VPS时可以自托管获得对应用和数据的完全控制也便于在单台服务器上部署多个应用以降低成本代价是需要自己维护服务器。自托管部署文档 给出的一般流程为从应用代码构建服务端应用与客户端应用在服务器上设置服务端环境变量在服务器上运行数据库或使用托管数据库服务运行服务端应用可用 Docker也可不用用静态文件服务器托管客户端应用设置反向代理Nginx、Caddy、Traefik 等使应用可通过域名 HTTPS 访问。推荐的域名规划是客户端用myapp.com、服务端用api.myapp.com反向代理在myapp.com上托管客户端静态文件并把 API 请求代理到服务端应用同时确保 环境变量 使用这些域名。自托管时的数据库运维需要自行负责备份、升级与扩缩容建议为 PostgreSQL 配置定期备份和/或服务器磁盘快照若不想自运维可选择 AWS RDS、DigitalOcean Managed Databases、Supabase 等托管服务。仓库还提供了 CapRover、Coolify、纯 DockerUbuntu Git Caddy等具体自托管指南见 web/docs/guides/deployment/self-hosted。自定义 Dockerfile 钩子Wasp 默认生成多阶段 Dockerfile用于构建并运行服务端镜像同时会执行待应用的迁移。你可以在项目根目录创建自己的DockerfileWasp 检测到后会把其内容追加到默认多阶段 Dockerfile 的底部——由于 Dockerfile 中最后定义者生效你可以覆盖或延续任意构建阶段甚至可以完全不用 Wasp 的构建阶段而让自定义 Dockerfile 原样生效。需要注意若覆盖了中间构建阶段后续阶段将不再使用除非你在下方自行重现生成的 Dockerfile 内容随应用功能动态变化且未来版本可能变动请定期核实最终构建阶段必须提供ENTRYPOINT否则你的改动不会生效。想查看项目最终可能已合并的Dockerfile 内容可运行wasp dockerfileCI/CD让部署自动化为应用配置 CI/CD 流水线是强烈推荐的实践。CI/CD 文档 将其分为两部分CI持续集成在代码推送时自动验证/测试代码及早发现 bugCD持续部署将代码变更自动部署到生产环境即push to deploy。在 CI 中运行测试端到端e2e测试模拟真实用户操作登录、加入购物车等在 CI 中运行的步骤为①在 CI 环境安装 Wasp②在 CI 环境运行应用含数据库③对运行中的应用执行 e2e 测试。仓库示例应用examples/ask-the-documents、examples/kitchen-sink 等均带有 Playwright e2e 测试目录与playwright.config.ts配置可作参考。典型 e2e 测试用例Playwrightimport { 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) }) })单元测试更简单快速但无法模拟真实用户交互。Wasp 内置客户端测试支持wasp test client run服务端可选用任意测试框架项目测试文档 有详细说明。持续部署的两条路径路径一用 Docker 打包服务端与客户端。这是最常用的方式同一镜像可轻松部署到 staging、production 等不同环境。流程为①在 CD 环境安装 Docker②wasp install安装依赖并用wasp build构建③构建并推送服务端、客户端的 Docker 镜像到镜像仓库如 Docker Hub、GHCR④对部分提供商通过 Webhook 通知其部署新版本。路径二客户端作为静态文件部署。客户端是 SPA构建产物只是静态 HTML/CSS/JS可直接上传到任意静态托管商通常比托管 Docker 镜像更便宜。流程为①在 CD 环境wasp installwasp build②npx vite build构建客户端③将.wasp/out/web-app/build中的静态文件上传到托管商。上线后的进阶配置自定义域名、CDN 与生产就绪性自定义域名客户端与服务器都可配置自定义域名其中客户端域名是用户浏览器访问的入口更为关键服务器域名则用于隐藏 IP 地址或自动生成域名等细节。设置过程分两步配置 DNS 记录在 DNS 设置中添加指向应用 IPv4 地址的A记录通常同时配置 IPv6 的AAAA记录部分提供商要求用CNAME记录替代。使用wasp deploy时可参考 Fly.io 自定义域名 或 Railway 自定义域名。设置环境变量构建客户端时设置REACT_APP_API_URL指向服务器域名如REACT_APP_API_URLhttps://api.myapp.com服务器侧配置两个变量——WASP_WEB_CLIENT_URLhttps://myapp.com与WASP_SERVER_URLhttps://server.myapp.com以保证 CORS 等行为正确。CDN 与 DDoS 防护在生产环境可考虑使用 CDN 与 DDoS 防护服务CDN全球分布的缓存服务器网络缓存图片、CSS、JS 等静态资源。在客户端前放置 CDN 可加速全球用户的资源加载就近服务。若客户端也通过自定义域名服务REACT_APP_API_URL应指向服务器域名。DDoS 防护攻击者以大量流量压垮服务器使其无法服务合法用户。可为客户端与服务器同时启用 DDoS 防护服务。文档推荐使用 Cloudflare 同时承担 CDN 与 DDoS 防护免费额度对大多数中小型应用足够Fastly、Bunny、Amazon CloudFront 等也是可选方案。Wasp 应用的生产就绪性回到开头提到的三组件架构Wasp 应用由 Node.js Express 服务端、PostgreSQL 数据库、React Vite 客户端组成每一部分本身都是久经考验的生产级组件Wasp 只是让它们更容易连接在一起。同时需要留意Wasp 目前仍处于 beta 阶段可能存在个别粗糙之处部署前建议用wasp build start做好本地预演并按上文清单逐项核对环境变量与数据库配置。总结部署 Wasp 应用的本质是把客户端 SPA Express 服务端 PostgreSQL 数据库这三个独立组件分别交付到生产环境并通过环境变量与 HTTP 通信将它们串联起来。掌握了wasp build产物结构、生产环境变量规则、迁移机制、wasp build start本地预演以及一键部署、云端、自托管、CI/CD 等不同路径后你就可以根据自己的基础设施与预算选择最合适的上线方案。相关文档均可在仓库的 web/docs/deployment 目录下继续深入查阅。【免费下载链接】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），仅供参考
