Wasp 应用 PaaS 云平台部署完全指南Fly.io / Railway / Heroku / Netlify / Cloudflare 实战【免费下载链接】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 全栈应用部署到主流 PaaS平台即服务云平台。Wasp 构建产物分为 Node.js API 服务端、静态 Web 客户端与 PostgreSQL 数据库三部分本文会依次讲解通用的四步部署流程wasp build生成产物 → 部署后端 → 部署前端 → 部署数据库再分别给出 Fly.io、Railway、Heroku、Netlify、Cloudflare 五个平台的完整操作步骤包括环境变量配置、Docker 镜像推送、GitHub Actions 自动部署等实战细节。读完本文你将能够把任意 Wasp 应用按官方推荐方式部署到生产环境并理解其背后的构建产物结构与配置原理。部署总览Wasp 应用由三部分组成Wasp 应用是典型的三层全栈应用每一层都可以独立部署Node.js API 服务端Server处理业务逻辑、鉴权、数据库访问通常以 Docker 镜像形式运行静态 Web 客户端ClientReact 前端构建产物是一堆静态文件可托管到任意静态托管平台PostgreSQL 数据库Database生产环境唯一支持的数据库需要保持运行并可从服务端访问。因此部署一个 Wasp 应用本质上就是完成以下四件事生成可部署代码wasp build部署 API 服务端后端部署 Web 客户端前端部署并维持一个 PostgreSQL 数据库。你完全可以把三部分拆开部署到不同平台例如前端放 Netlify、后端放 Fly.io、数据库用托管服务只要满足各自的运行前提即可。第 1 步生成可部署代码在 Wasp 项目根目录运行构建命令wasp build该命令会把整个应用的可部署代码生成到.wasp/build/目录。生成结果中包含服务端的Dockerfile用于构建并运行服务端镜像服务端源码与依赖Web 客户端源码位于.wasp/build/web-app/需要进一步构建成静态文件。:::caution 生产环境必须使用 PostgreSQL 如果你正在使用 SQLiteWasp 的默认开发数据库将无法构建应用。Wasp 官方明确说明SQLite 只用于开发阶段部署到生产环境前必须先迁移到 PostgreSQL。迁移步骤参见 从 SQLite 迁移到 PostgreSQL。具体做法是把schema.prisma中的provider从sqlite改为postgresql并保证开发期有可访问的 PostgreSQL 实例wasp start、wasp db migrate-dev等命令都依赖数据库连接。 :::自定义服务端 Dockerfile默认情况下Wasp 会生成一个多阶段Dockerfile用于构建服务端镜像并运行任何待执行的数据库迁移。若需定制你可以在项目根目录放一个自己的DockerfileWasp 会把它追加到默认多阶段 Dockerfile 的底部。由于 Docker 遵循后定义者生效的规则你既可以覆盖已有构建阶段也可以完全绕开 Wasp 的阶段使用自己的 Dockerfile。需要留意的是若你覆盖了某个中间构建阶段其后的默认阶段将不再生效除非你在自己的内容里重新实现生成的 Dockerfile 内容随应用启用的功能动态变化未来版本也可能调整建议定期核对最终构建阶段必须提供ENTRYPOINT否则改动不会生效。想预览项目最终的合并后的Dockerfile可运行wasp dockerfile更多细节见 部署总览。仓库中的真实项目也体现了这一模式例如 examples/kitchen-sink/Dockerfile 就是 Wasp 应用根目录的自定义 Dockerfile 实例。第 2 步部署 API 服务端后端.wasp/build目录中存在一个定义服务端镜像的Dockerfile。生产环境部署时你需要把这个 Docker 镜像部署到托管平台Fly.io、Heroku、Railway 等均可通过平台的控制台或 CLI 正确设置服务端所需的环境变量。服务端必需的环境变量见 部署相关的环境变量说明核心几项如下取自 项目环境变量文档 中的服务端通用配置环境变量类型是否必填说明DATABASE_URLString必填应用要连接的 PostgreSQL 数据库 URLWASP_WEB_CLIENT_URLURL必填服务端在各类功能中使用的客户端地址例如在邮件中链接到你的应用WASP_SERVER_URLURL必填服务端对外暴露的自身地址例如 OAuth 登录Google、GitHub后用于重定向用户JWT_SECRETString必填至少 32 字符的随机字符串用于生成安全令牌PORTInteger可选服务端监听端口默认3001值得强调的两个关键点生产环境下.env.server文件会被忽略服务端环境变量必须通过托管平台提供的机制如fly secrets set注入若应用启用了外部认证如 Google、GitHub 社交登录还需额外设置这些认证方式专属的环境变量例如GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET。第 3 步部署 Web 客户端前端先进入前端构建目录cd .wasp/build/web-app然后安装依赖并构建生产产物把url_to_wasp_backend替换为你已部署的服务端 URLnpm install REACT_APP_API_URLurl_to_wasp_backend npm run build构建产物纯静态文件位于.wasp/build/web-app/build/。之后把该目录内容部署到任意静态托管平台如 Netlify、Cloudflare即可。关于客户端环境变量有两个关键注意点详见 客户端环境变量客户端环境变量在构建阶段被注入客户端 JS 代码任何人都能读取因此绝不能存放密钥如 API Secret生产环境会忽略.env.client文件且不能通过托管平台为客户端设置环境变量——客户端产物只是静态文件运行时无法注入。正确做法是把变量直接拼到构建命令前面例如REACT_APP_SOME_VARsomevalue npm run build。其底层原理是Wasp 在构建过程中会把客户端代码中所有import.meta.env.REACT_APP_SOME_VAR的出现替换为你在构建命令中提供的值替换发生在构建期值因此被固化进静态文件中。第 4 步部署 PostgreSQL 数据库任何 PostgreSQL 数据库都可以前提是为服务端提供正确的DATABASE_URL环境变量确保数据库能被服务端访问网络连通、防火墙放行。你可以使用平台自带的数据库服务如 Fly.io 的 PostgreSQL、Heroku Postgres、Railway 的 PostgreSQL 模板也可以使用外部托管数据库如 Neon、Supabase、AWS RDS甚至自托管。若不想自己维护数据库的备份、升级与扩容托管数据库是更省心的选择。五大 PaaS 平台部署实战下面按官方指南逐个演示五个平台的部署。官方同时提供了一个更省事的选择——Wasp DeployWasp CLI 可以用一条命令自动部署客户端、服务端和数据库对应 Fly.io 的 Wasp Deploy 指南 与 Railway 的 Wasp Deploy 指南。下面的手动步骤则能让你对每个环节有完全的控制。Fly.io服务端 数据库Fly.io 是一个运行容器化应用与微服务的全球平台。本节演示如何在其上部署服务端并为它准备数据库。前置条件注册 Fly.io 账号安装flyCLI用flyCLI 登录。可用fly auth whoami检查登录状态未登录则执行fly auth login。创建 Fly.io 应用每个 Wasp 应用只需一次先完成wasp build然后进入.wasp/build/目录cd .wasp/build执行 launch 命令创建新应用并生成fly.tomlfly launch --remote-only期间会询问一系列问题选择区域、是否需要数据库等请这样回答对Would you like to set up a PostgreSQL database now?回答yes并选择Development方案——Fly.io 会自动为你设置DATABASE_URL对Would you like to deploy now?回答no以及其余附加问题因为我们还需要配置若干环境变量。:::info 数据库创建失败怎么办 如果初始化应用失败先执行fly apps destroy app-name再重试——Fly 不允许创建同名应用。数据库部署成功后你可以在 Fly.io 控制台看到它。 :::接着把fly.toml复制回 Wasp 项目根目录妥善保存wasp build每次会清空.wasp/build/这份文件留在项目目录里就不会丢失cp fly.toml ../../然后为服务端设置环境变量fly secrets set PORT8080 fly secrets set JWT_SECRETrandom_string_at_least_32_characters_long fly secrets set WASP_WEB_CLIENT_URLurl_of_where_client_will_be_deployed fly secrets set WASP_SERVER_URLurl_of_where_server_will_be_deployedJWT_SECRET需要至少 32 字符的随机字符串。如果此时还不知道客户端 URL没关系WASP_WEB_CLIENT_URL可以在客户端部署完成后再设置。若应用启用了 Google、GitHub 等外部认证记得一并设置对应的 OAuth 环境变量。确认是否设置成功可运行fly secrets list注意出于安全考虑展示的是哈希后的值。部署到 Fly.io仍在.wasp/build/目录下运行fly deploy --remote-only --config ../../fly.toml这会构建并部署 Wasp 后端到https://app-name.fly.dev。之后若还没部署客户端可以部署完客户端再设置fly secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client。官方建议客户端用 Netlify但任意静态托管平台都可以。常用fly命令fly logs # 查看日志 fly secrets list fly ssh console # 进入容器调试重新部署的注意事项每次执行wasp build都会清空.wasp/build/目录其中可能存有之前生成的fly.toml。处理方式有三种把fly.toml复制到版本化目录如项目根目录之后用fly deploy --config path引用它在wasp build之前备份fly.toml构建完成后复制回.wasp/build/——此时无需指定--config运行fly config save -a app-name从 Fly.io 远程状态重新生成fly.toml。仓库中的真实示例可以印证fly.toml的结构例如 examples/waspello/fly-server.toml其中包含app名、primary_region、http_service.internal_port 8080、force_https true以及 VM 资源配置memory、cpus等。Railway服务端 客户端 数据库Railway 可以同时承载服务端、客户端静态托管和 PostgreSQL 数据库。前置条件先在项目目录运行wasp build注册 Railway 账号安装 Railway CLI运行railway login浏览器会打开页面完成认证。创建 Railway 项目进入 Railway 控制台点击New Project从下拉菜单选择Deploy PostgreSQL项目创建后点击右上角Create按钮选择Empty Service点击新服务把名称改为server再创建一个空服务命名为client点击顶部Deploy按钮部署这些变更。配置域名server和client两个服务都需要域名进入server实例的Settings标签页点击Generate Domain端口填8080然后点击Generate Domain对client的Settings做同样操作复制两个域名备用。部署服务端进入.wasp/build目录cd .wasp/build把该目录链接到 Railway 项目railway link提示选择服务时选server。在 Railway 控制台为server服务设置环境变量Variables标签页点击Variable reference选择DATABASE_URL会自动填入正确值添加WASP_WEB_CLIENT_URL值为client域名如https://client-production-XXXX.up.railway.app必须带https://前缀添加WASP_SERVER_URL值为server域名如https://server-production-XXXX.up.railway.app必须带https://前缀添加JWT_SECRET值为至少 32 字符的随机字符串若启用了外部认证补充对应 OAuth 环境变量。推送并部署railway up --ci--ci标志用于把日志输出限制为仅构建过程。Railway 会识别.wasp/build中的Dockerfile并部署服务端。部署客户端进入前端构建目录cd web-app构建生产产物REACT_APP_API_URL填服务端域名npm install REACT_APP_API_URLurl_to_wasp_backend npm run build把客户端构建目录链接到client服务cd build railway link部署客户端railway up --ci提示选择服务时选client。Railway 检测到index.html后会把客户端作为静态站点部署。部署完成后回到 Railway 控制台就能看到 PostgreSQL、Server、Client 三个服务。更新与重新部署运行wasp build重新构建应用进入.wasp/build目录用railway up --ci部署服务端进入.wasp/build/web-app目录用npm install REACT_APP_API_URLurl_to_wasp_backend npm run build重建客户端再cd build railway up --ci部署客户端。Heroku服务端 数据库Heroku 的付费方案信息可查看其官网定价页。本节需要 Heroku 账号、herokuCLI 和dockerCLI。用heroku whoami检查登录状态未登录则执行heroku login。创建 Heroku 应用每个 Wasp 应用只需一次heroku create app-name创建数据库如无外部 PostgreSQL 可复用heroku addons:create --app app-name heroku-postgresql:essential-0:::caution 关于 essential-0essential-0是 Heroku 提供的最便宜的数据库实例$5/月。 :::Heroku 会自动设置DATABASE_URL若使用外部数据库则需要自行配置。PORT环境变量也由 Heroku 提供因此只需设置其余三项heroku config:set --app app-name JWT_SECRETrandom_string_at_least_32_characters_long heroku config:set --app app-name WASP_WEB_CLIENT_URLurl_of_where_client_will_be_deployed heroku config:set --app app-name WASP_SERVER_URLurl_of_where_server_will_be_deployed若暂时不知道客户端 URLWASP_WEB_CLIENT_URL可留待客户端部署后再设置。部署 Heroku 应用完成wasp build后进入.wasp/build/目录假设你此时位于 Wasp 项目根目录cd .wasp/build登录 Heroku 容器仓库heroku container:login把应用 stack 设为container以便以 Docker 容器方式部署heroku stack:set container --app app-name构建 Docker 镜像并推送到 Herokuheroku container:push --app app-name web此步骤比较耗时尤其首次推送因为没有缓存的 Docker 层。注意此时应用尚未部署。发布镜像并重启应用heroku container:release --app app-name web至此后端部署完成位于https://app-name-XXXX.herokuapp.com。用heroku info --app app-name可查看确切 URL用heroku logs --tail --app app-name可实时查看日志。:::note 在 Heroku 上使用 pg-boss 任务 如果你的应用使用了 后台任务Jobs且任务的执行器为pg-boss例如在main.wasp.ts中声明executor: PgBoss的 Job部署到 Heroku 时还需要额外设置一个环境变量PG_BOSS_NEW_OPTIONS{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}原因是 pg-boss 依赖的pg扩展默认不通过 SSL 连接数据库而 Heroku 要求 SSL 连接且其证书为自签名因此需要按上述方式显式处理。 :::Netlify客户端Netlify 是免费的静态托管方案适用于大多数场景。需要 Netlify 账号。用npx netlify-cli status检查登录状态未登录则执行npx netlify-cli login。先完成wasp build然后构建客户端cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build部署客户端npx netlify-cli deploy按提示仔细操作决定创建新应用还是使用已有应用、选择部署所属团队等。最后发布到生产npx netlify-cli deploy --prod客户端上线于https://app-name.netlify.app。:::note 务必把https://app-name.netlify.app设置为服务端托管环境中的WASP_WEB_CLIENT_URL环境变量。 ::::::caution URL 重定向到 index.html 按上述方式操作时Netlify CLI 会使用 Wasp 默认生成在.wasp/build/web-app/中的netlify.toml它会正确配置 Netlify 把 URL 重定向到index.html——这对 Wasp 客户端至关重要因为 Wasp 是单页应用SPA需要由客户端处理路由。如果改用其他方式部署到 Netlify例如通过 CI请确保 Netlify 能读取该netlify.toml或手动配置 URL 重定向规则。官方推荐在 GitHub Actions 中使用 Netlify CLI 部署。 :::通过 GitHub Actions 自动部署在仓库创建.github/workflows/deploy.yaml即可在每次推送到main分支时自动部署客户端文件名可改扩展名须保持.yamlname: Deploy Client to Netlify 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: 22 - name: Install Wasp run: curl -sSL https://get.wasp.sh/installer.sh | sh -s -- -v 0.16.0 # Change to your Wasp version - name: Wasp Build run: wasp build - name: Install dependencies and build the client run: | cd ./.wasp/build/web-app npm install REACT_APP_API_URL${{ secrets.WASP_SERVER_URL }} npm run build - name: Deploy to Netlify run: | cd ./.wasp/build/web-app npx netlify-cli17.36.1 deploy --prod --dirbuild --auth$NETLIFY_AUTH_TOKEN --site$NETLIFY_SITE_NAME env: NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} NETLIFY_SITE_NAME: netlify-site-name工作流所需的环境变量NETLIFY_AUTH_TOKEN在 Netlify 上生成的 Personal Access TokenNETLIFY_SITE_NAMENetlify 项目名称WASP_SERVER_URL服务端 URL一般要等后端部署完成后才有后端未部署时可跳过该变量但需知悉依赖后端的功能会不可用。这些变量需要配置到 GitHub 仓库的 Secrets 中。Cloudflare客户端Cloudflare 提供多项云服务其中包括免费的静态托管 Cloudflare Pages。需要 Cloudflare 账号。用 WranglerCloudflare 官方 CLI登录npx wrangler login先完成wasp build然后构建客户端cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build在.wasp/buld/web-app目录下部署客户端npx wrangler pages deploy ./build --commit-dirtytrue --branchmain按提示操作创建新应用还是使用已有应用。客户端上线于https://app-name.pages.dev。:::note 务必把https://app-name.pages.dev设置为服务端托管环境中的WASP_WEB_CLIENT_URL环境变量。 ::::::info URL 重定向到 index.html Cloudflare 会自动把所有路径重定向到index.html这正好满足 Wasp 单页应用SPA由客户端处理路由的需求。 :::通过 GitHub Actions 自动部署在仓库创建.github/workflows/deploy.yaml在每次推送到main分支时自动部署到 Cloudflare Pagesname: 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: 22 - name: Install Wasp run: curl -sSL https://get.wasp.sh/installer.sh | sh -s -- -v 0.16.0 # Change to your Wasp version - name: Wasp Build run: cd ./app wasp build - name: Install dependencies and build the client run: | cd ./app/.wasp/build/web-app npm install REACT_APP_API_URL${{ secrets.WASP_SERVER_URL }} npm run build - name: Deploy to Cloudflare Pages uses: cloudflare/wrangler-actionv3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} command: pages deploy ./app/.wasp/build/web-app/build --project-name${{ env.CLIENT_CLOUDFLARE_APP_NAME }} --commit-dirtytrue --branchmain env: CLIENT_CLOUDFLARE_APP_NAME: cloudflare-pages-app-name工作流所需的环境变量CLOUDFLARE_API_TOKEN和CLOUDFLARE_ACCOUNT_ID在 Cloudflare 控制台的 API Tokens 页面获取令牌需具备Cloudflare Pages: Read和Cloudflare Pages: Edit权限CLIENT_CLOUDFLARE_APP_NAMECloudflare Pages 应用名称可用npx wrangler pages project create app-name创建WASP_SERVER_URL服务端 URL同上一般需在部署后端后才有后端未部署时可跳过但相关功能会不可用。同样需要把这些变量配置到 GitHub 仓库的 Secrets 中。部署清单与常见问题无论选择哪个平台部署前请对照以下清单逐项确认数据库已切换为 PostgreSQLschema.prisma中provider postgresql且已完成从 SQLite 的迁移服务端环境变量齐全DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET四项必填PORT按平台要求设置Fly.io 用 8080Heroku 自动提供Railway 在生成域名时指定 8080外部认证变量已补充使用 Google / GitHub 等社交登录时额外设置对应 OAuth 环境变量客户端环境变量已注入构建命令REACT_APP_API_URL指向服务端 URL其他客户端变量一并写在构建命令前且不存放任何密钥SPA 重定向已配置Netlify 需依赖 Wasp 生成的netlify.tomlCloudflare 则自动重定向到index.htmlfly.toml等部署配置已纳入版本控制避免wasp build清空.wasp/build/后丢失。一个常见的疑问是wasp build每次都会重建产物目录会不会影响部署配置答案见各平台的重新部署小节——Fly.io 的fly.toml建议保存在项目根目录仓库示例见 examples/waspello/fly-server.tomlNetlify 的netlify.toml由 Wasp 自动生成在构建目录内只要通过官方推荐方式部署即可正确生效。如果你的首选平台不在上述列表中也无需担心——只要它支持 Wasp 的构建格式Docker 镜像 静态文件 PostgreSQL都可以部署只是暂时没有对应的逐步指南。官方还提供了 Wasp Deploy 一键部署方案可让 Wasp CLI 自动完成客户端、服务端与数据库的部署与配置进一步降低多平台手动操作的成本。【免费下载链接】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），仅供参考