Wasp 应用 PaaS 部署完全指南：Fly.io / Railway / Heroku / Netlify / Cloudflare 实战

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 框架（GitHub_Trending/wa/wasp 仓库）version-0.16 版 PaaS 部署文档 为核心骨架，系统讲解如何把一个 Wasp 全栈应用（Node.js 服务端 + 静态客户端 + PostgreSQL 数据库）构建为可部署产物，并逐步部署到 Fly.io、Railway、Heroku、Netlify、Cloudflare 五大主流 PaaS 平台。读完本文，你将掌握wasp build产物结构、服务端/客户端/数据库三部分的分平台部署流程、生产环境环境变量配置，以及基于 GitHub Actions 的自动化持续部署方案。

Wasp 应用本质上是三部分的组合：一个 Node.js API 服务端、一个静态 React 客户端、一个 PostgreSQL 数据库。部署的本质就是把这三种形态各异的产物分别放到合适的托管环境里。本文先讲通用的构建与准备步骤，再分平台给出可复制的操作命令，最后补充仓库内的真实配置样本与源码证据，帮助你理解每一步背后的产物结构。

部署全景：Wasp 应用的四个部署步骤

无论部署到哪个平台，Wasp 应用的部署都归结为以下四步：

1. 生成可部署代码：运行wasp build得到整个应用的部署产物；
2. 部署 API 服务端（后端）：将产物中的服务端 Docker 镜像部署到支持容器的托管平台；
3. 部署 Web 客户端（前端）：将产物中的静态文件部署到任意静态托管平台；
4. 部署 PostgreSQL 数据库：为服务端提供正确的DATABASE_URL并保证数据库可从服务端访问。

下面逐一展开。

1. 生成可部署代码：wasp build

在项目根目录运行：

wasp build

该命令会在.wasp/build/目录下生成整个应用的可部署代码。这一目录随后会成为所有部署操作的工作基准：

• 服务端的 Dockerfile 位于.wasp/build目录中，用于构建服务端镜像；
• 客户端的构建产物位于.wasp/build/web-app/（详见下文）；
• 手动部署时通常需要cd .wasp/build进入该目录执行平台 CLI 命令。

⚠️ 生产环境必须使用 PostgreSQL如果你还在使用 SQLite（Wasp 的默认数据库），wasp build会构建失败。上线前必须从 SQLite 迁移到 PostgreSQL。生产部署的数据库选型与迁移细节可参考数据模型与数据库文档。

2. 部署 API 服务端

.wasp/build目录中有一个用于构建服务端镜像的 Dockerfile。将镜像部署到任意托管平台，并确保所需环境变量正确设置（通常通过平台的控制台或 CLI 设置），服务端即告上线。

服务端必需的环境变量清单在下文专门小节列出。关于自定义该 Dockerfile（例如在其底部追加构建阶段）的方法，可参考部署总览文档——你可以在项目根目录放一个自定义Dockerfile，Wasp 会将其内容追加到默认多阶段 Dockerfile 的底部，并用wasp dockerfile命令预览合并结果。

3. 部署 Web 客户端

构建客户端前，先进入前端构建目录：

cd .wasp/build/web-app

然后安装依赖并构建静态文件，其中<url_to_wasp_backend>是先前已部署的 Wasp 服务端 URL：

npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

如果你在项目中定义了其他客户端环境变量，也要一并追加到上述命令中（详见后文「客户端环境变量」）。

构建结果是.wasp/build/web-app/build/下的一批静态文件，可以部署到任何静态托管商（如 Netlify、Cloudflare）。这一步对应 PaaS 部署文档 中的「3. Deploying the Web Client」小节。

4. 部署数据库

任何 PostgreSQL 数据库都可以使用，前提是给服务端提供正确的DATABASE_URL环境变量，并保证数据库对服务端可达。不同平台数据库的获取方式各异：Fly.io 通过flyctl交互式创建，Railway 通过面板 Provision PostgreSQL，Heroku 通过 addons 创建，也可以使用外部托管数据库（如 AWS RDS、Neon、Supabase 等）。

生产环境环境变量：部署前的必修课

开发时我们习惯用.env.server和.env.client文件管理环境变量，但部署时这两个文件会被忽略，必须改用托管平台提供的机制注入环境变量。详细的开发/生产环境变量差异可参考部署环境变量文档。

服务端环境变量

Wasp 内置校验的服务端环境变量（来自 version-0.16 项目环境变量文档）：

除上述通用配置外，根据使用功能还可能需要：SMTP 发信（SMTP_HOST、SMTP_PORT、SMTP_USERNAME、SMTP_PASSWORD）、SendGrid（SENDGRID_API_KEY）、Mailgun（MAILGUN_API_KEY、MAILGUN_DOMAIN、MAILGUN_API_URL）、OAuth（<PROVIDER_NAME>_CLIENT_ID与_CLIENT_SECRET，如GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET）、Jobs 任务队列（PG_BOSS_NEW_OPTIONS，按 JSON 解析）。

💡 使用外部认证方式？如果应用启用了 Wasp 支持的 Google、GitHub 等外部认证，还需要额外设置这些认证方式各自要求的环境变量（如GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET），详见认证总览文档。这一提醒在部署文档的辅助片段中也有强调。

客户端环境变量

客户端环境变量在构建阶段被注入到客户端 JavaScript 代码中，任何人查看静态文件都能读到，因此绝不能存放密钥（如 API 密钥）。生产构建时.env.client被忽略，需要把客户端环境变量直接传给构建命令：

REACT_APP_API_URL=<url_to_wasp_backend> REACT_APP_SOME_OTHER_VAR_NAME=someothervalue npm run build

注意：不能也不应该通过在托管平台上设置环境变量来给客户端代码注入变量——客户端部署后只是静态文件，会忽略这些变量。其原理是 Wasp 在构建过程中把客户端代码里所有import.meta.env.REACT_APP_SOME_VAR_NAME替换为对应的值。客户端代码中统一通过import { env } from 'wasp/client'读取，服务端通过import { env } from 'wasp/server'读取，二者都经过 Wasp 内置的 Zod 校验。

⚠️ 必设服务端环境变量部署时必须逐一核对上述所有必需的服务端环境变量（DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET）并在生产环境设置好。如果使用 Wasp CLI 部署，Wasp 会自动设置通用配置变量，但 OAuth 密钥等其余变量仍需你自行配置。

Fly.io：服务端 + 数据库一键部署

Fly.io 提供丰富的免费额度，非常适合部署第一个 Wasp 应用。本节展示如何手动在 Fly.io 部署服务端并为其配置数据库（这也是部署总览中推荐的组合方式）。如果你希望把下面的工作浓缩为一条命令，可以直接使用 Wasp CLI 的wasp deploy fly系列命令，它一条命令即可完成服务端、客户端与数据库的全部部署。

前置准备

• 一个 Fly.io 账号；
• 安装flyctlCLI（大多数系统上fly是flyctl的符号链接，二者可互换）；
• 登录检查：flyctl auth whoami，未登录则执行flyctl auth login。

说明：Fly.io 同时支持本地构建和远程构建 Docker 镜像。为了可重复性，本文默认使用 Fly.io 的远程构建器（--remote-only）。

初始化 Fly.io 应用（每应用只需一次）

先完成构建，然后进入.wasp/build/目录：

cd .wasp/build

运行 launch 命令创建新应用并生成fly.toml配置文件：

flyctl 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（以及其余附加问题都选否），因为我们还需要先设置几个环境变量。

如果数据库创建失败怎么办？若初始化新应用失败，先运行flyctl apps destroy <app-name>再重试。Fly 不允许创建多个同名应用。数据库正确部署后，你可以在 Fly.io 仪表盘 看到对应条目（见下图）。

接下来把fly.toml复制回项目根目录妥善保存（wasp build会清空.wasp/build/，详见「重新部署」小节）：

cp fly.toml ../../

然后为服务端代码补充几个环境变量：

flyctl secrets set PORT=8080 flyctl secrets set JWT_SECRET=<random_string_at_least_32_characters_long> flyctl secrets set WASP_WEB_CLIENT_URL=<url_of_where_client_will_be_deployed> flyctl secrets set WASP_SERVER_URL=<url_of_where_server_will_be_deployed>

如果还不知道客户端 URL，不必担心，可以等客户端部署完成后再设置WASP_WEB_CLIENT_URL。使用外部认证的应用记得追加对应密钥。校验配置可运行flyctl secrets list（显示的是脱敏后的哈希值）。

部署到 Fly.io

仍在.wasp/build/目录下执行：

flyctl deploy --remote-only --config ../../fly.toml

这会构建并部署 Wasp 应用的后端到https://<app-name>.fly.dev。之后（若尚未完成）可以部署客户端，并把客户端 URL 通过flyctl secrets set WASP_WEB_CLIENT_URL=<url_of_deployed_client>补上——文档建议客户端用 Netlify 托管，也可以选择任意静态托管商。

一些实用的flyctl命令：

flyctl logs # 查看日志 flyctl secrets list # 查看已设置的密钥 flyctl ssh console # 进入应用控制台

重新部署：wasp build之后的fly.toml处理

每次wasp build重新构建应用时，.wasp/build/目录都会被清空，其中可能包含上次 Fly.io 部署留下的fly.toml。目前有以下三种处理方式：

1. 把fly.toml放到版本控制目录（如项目根目录），部署时通过flyctl deploy --config <path>引用它（即上文做法）；
2. 构建前备份fly.toml，wasp build之后复制回.wasp/build/目录。当fly.toml存在于.wasp/build/时，无需再指定--config <path>；
3. 运行flyctl config save -a <app-name>，从 Fly.io 的远端状态重新生成fly.toml。

仓库中的真实 Fly 配置样本

本仓库的 waspello 示例 就包含 Wasp CLI 生成的 Fly 配置文件，可作为配置格式的参照：

• examples/waspello/fly-server.toml：服务端应用配置，http_service.internal_port = 8080与上文PORT=8080的密钥设置相互印证，min_machines_running = 1保证服务端常驻；
• examples/waspello/fly-client.toml：客户端应用配置，internal_port = 8043、min_machines_running = 0（客户端是静态托管，可按需启停）。

使用 Wasp CLI 部署 时，Wasp 会在项目根目录生成fly-server.toml与fly-client.toml两个文件（对应三个独立 Fly 应用：<name>-client、<name>-server、<name>-db），并建议将这两个 TOML 纳入版本控制，之后即可用单条wasp deploy fly deploy完成更新部署。

Railway：服务端 + 客户端 + 数据库全栈部署

Railway 适合同时托管服务端和数据库，也支持把数据库、服务端、客户端整套部署上去。平台提供限时免费额度或符合条件时的免费使用。

前置准备

1. 在项目目录运行wasp build完成构建；
2. 注册 Railway 账号（用 GitHub 账号注册可获得免费额度资格）；
3. 安装 Railway CLI；
4. 运行railway login，浏览器会打开完成身份认证。

创建 Railway 项目

1. 打开 Railway 仪表盘，点击New Project，从下拉菜单中选择Provision PostgreSQL；
2. 初始化完成后，右键点击右上角的New按钮，选择Empty Service；
3. 初始化后点击该服务，进入Settings > General，把名称改为server；
4. 再创建一个空服务，命名为client。

部署应用到 Railway

配置域名

server和client两个服务都需要域名：

1. 进入server实例的Settings选项卡，点击Generate Domain；
2. 对client的Settings重复同样操作。

记下两个域名，后面会用到。

部署服务端

1. 进入应用的.wasp/build/目录：

cd .wasp/build

2. 将构建产物链接到刚创建的 Railway 项目：

railway link

3. 在 Railway 仪表盘中设置必需环境变量（打开Settings进入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 字符的随机字符串；
   • 使用外部认证的应用需额外追加对应密钥。

4. 推送并部署项目：

railway up

在Select Service提示时选择server。Railway 会自动找到 Dockerfile 并部署你的服务端。

部署客户端

1. 进入前端构建目录：

cd web-app

2. 用server域名作为REACT_APP_API_URL构建生产产物：

npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

3. 同样把这个前端目录链接到项目：

railway link

4. 配置 Railway 的静态托管。关键点：把web-app目录下的build文件夹复制为dist：

cp -r build dist

然后创建两个文件：

• Dockerfile：

FROM pierrezemb/gostatic CMD [ "-fallback", "index.html" ] COPY ./dist/ /srv/http/

• .dockerignore：

node_modules/

注意：每次运行wasp build都会清空.wasp/build/web-app目录，因此这些步骤每次都要重复执行。文档提供了一个自动化脚本deploy_client.sh，可放在项目根目录：

#!/usr/bin/env bash if [ -z "$REACT_APP_API_URL" ] then echo "REACT_APP_API_URL is not set" exit 1 fi wasp build cd .wasp/build/web-app npm install && REACT_APP_API_URL=$REACT_APP_API_URL npm run build cp -r build dist dockerfile_contents=$(cat <<EOF FROM pierrezemb/gostatic CMD [ "-fallback", "index.html" ] COPY ./dist/ /srv/http/ EOF ) dockerignore_contents=$(cat <<EOF node_modules/ EOF ) echo "$dockerfile_contents" > Dockerfile echo "$dockerignore_contents" > .dockerignore railway up

赋予执行权限并运行：

chmod +x deploy_client.sh REACT_APP_API_URL=<url_to_wasp_backend> ./deploy_client.sh

5. 在Variables选项卡下把PORT环境变量设置为8043。这个端口与仓库中 examples/waspello/fly-client.toml 的internal_port = 8043一致，都是客户端静态服务的约定端口；
6. 部署客户端，Select Service时选择client：

railway up

完成后回到 Railway 仪表盘，即可看到三个已部署的服务：PostgreSQL、Server、Client。

更新与重新部署

• 运行wasp build重新构建应用；
• 在.wasp/build目录运行railway up（服务端）；
• 在.wasp/build/web-app目录重复全部客户端步骤。

Heroku：服务端 + 数据库部署

本节展示如何在 Heroku 部署服务端并为其创建数据库。需要 Heroku 账号、herokuCLI 和dockerCLI。用heroku whoami检查登录状态，未登录则heroku login。

创建 Heroku 应用（每应用只需一次）

创建新应用（或部署到已有应用）：

heroku create <app-name>

如果没有外部 PostgreSQL，在 Heroku 上创建数据库并挂载到应用：

heroku addons:create --app <app-name> heroku-postgresql:essential-0

⚠️ 成本提示：essential-0是 Heroku 最便宜的数据库实例，每月 $5。创建后 Heroku 会自动设置DATABASE_URL；若使用外部数据库则需自行配置。

PORT环境变量也由 Heroku 自动提供，因此只需设置剩下的三个变量：

heroku config:set --app <app-name> JWT_SECRET=<random_string_at_least_32_characters_long> heroku config:set --app <app-name> WASP_WEB_CLIENT_URL=<url_of_where_client_will_be_deployed> heroku config:set --app <app-name> WASP_SERVER_URL=<url_of_where_server_will_be_deployed>

不知道客户端 URL 也没关系，可以在部署完客户端后再设置WASP_WEB_CLIENT_URL。

部署 Heroku 应用

构建完成后进入.wasp/build/目录（假设此时位于 Wasp 项目根目录）：

cd .wasp/build

登录 Heroku 容器镜像仓库：

heroku container:login

把应用堆栈设置为container，以便以 Docker 容器方式部署：

heroku stack:set container --app <app-name>

构建 Docker 镜像并推送到 Heroku（首次构建没有缓存层，可能耗时较长；此时应用尚未真正部署）：

heroku container:push --app <app-name> web

部署推送的镜像并重启应用：

heroku container:release --app <app-name> web

至此后端部署完成，位于https://<app-name>-XXXX.herokuapp.com。用以下命令确认确切 URL 或查看日志：

heroku info --app <app-name> heroku logs --tail --app <app-name>

📌 在 Heroku 上使用pg-bossJobs如果要部署使用pg-boss作为执行器的 Jobs 任务，需要额外设置环境变量PG_BOSS_NEW_OPTIONS为{"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}。原因是 pg-boss 使用的pg扩展默认不以 SSL 连接（而 Heroku 强制要求 SSL），且 Heroku 使用自签名证书，需要显式放行。

Netlify：静态客户端部署

Netlify 是免费的静态托管方案（很多场景下免费），适合托管 Wasp 的客户端。需要 Netlify 账号，并登录 Netlify CLI（npx netlify-cli status检查，npx netlify-cli login登录）。

先完成wasp build，再按上文「3. 部署 Web 客户端」的步骤构建客户端静态文件。然后部署：

npx netlify-cli deploy

仔细跟随交互提示（创建新应用或使用现有应用、选择团队等）。最后一步执行：

npx netlify-cli deploy --prod

客户端即上线于https://<app-name>.netlify.app。

注意：记得把https://<app-name>.netlify.app设置为服务端托管环境中的WASP_WEB_CLIENT_URL环境变量。

⚠️ 把 URL 重定向到index.html按上述步骤操作时，Netlify CLI 会使用 Wasp 在.wasp/build/web-app/中默认生成的netlify.toml文件，它会正确配置 Netlify 把 URL 重定向到index.html。这对 Wasp 很重要，因为客户端是单页应用（SPA），需要在前端处理路由。如果你用其他方式部署（例如 CI），务必确保 Netlify 读取到这份netlify.toml，或在 Netlify 上手动配置 URL 重定向。

通过 GitHub Actions 自动部署

在仓库创建.github/workflows/deploy.yaml（可改名，但保持文件类型不变），即可在每次推送到main分支时自动部署客户端：

name: 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/checkout@v2 - name: Setup Node.js id: setup-node uses: actions/setup-node@v4 with: node-version: '20' - 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-cli@17.36.1 deploy --prod --dir=build --auth=$NETLIFY_AUTH_TOKEN --site=$NETLIFY_SITE_NAME env: NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} NETLIFY_SITE_NAME: netlify-site-name

工作流所需的三个环境变量（需配置在 GitHub Repository Secrets 中）：

• NETLIFY_AUTH_TOKEN：在 Netlify 生成 Personal Access Token；
• NETLIFY_SITE_NAME：Netlify 项目的名称；
• WASP_SERVER_URL：服务端 URL，通常在部署后端之后才可用。后端未部署或不可用时可以跳过该变量，但依赖后端的功能会失效。

Cloudflare：静态客户端部署

Cloudflare Pages 提供免费静态托管。需要 Cloudflare 账号，并登录 Wrangler CLI：

npx wrangler login

先完成wasp build与客户端构建，然后在.wasp/build/web-app目录下执行：

npx wrangler pages deploy ./build --commit-dirty=true --branch=main

跟随交互提示（创建新应用或使用现有应用）。客户端即上线于https://<app-name>.pages.dev。

注意：记得把https://<app-name>.pages.dev设置为服务端托管环境中的WASP_WEB_CLIENT_URL环境变量。

信息：Cloudflare 会自动把所有路径重定向到index.html，这对单页应用的客户端路由至关重要。

通过 GitHub Actions 自动部署

在仓库创建.github/workflows/deploy.yaml，每次推送到main分支时自动部署到 Cloudflare Pages：

name: 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/checkout@v2 - name: Setup Node.js id: setup-node uses: actions/setup-node@v4 with: node-version: '20' - 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-action@v3 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-dirty=true --branch=main env: CLIENT_CLOUDFLARE_APP_NAME: cloudflare-pages-app-name

工作流所需的环境变量：

• CLOUDFLARE_API_TOKEN和CLOUDFLARE_ACCOUNT_ID：从 Cloudflare 仪表盘的 API Tokens 页面获取，Token 需授予Cloudflare Pages: Read和Cloudflare Pages: Edit权限；
• CLIENT_CLOUDFLARE_APP_NAME：Cloudflare Pages 应用名，可用npx wrangler pages project create <app-name>创建；
• WASP_SERVER_URL：服务端 URL，通常在部署后端之后才可用；后端不可用时可跳过，但依赖后端的功能会失效。

平台能力速查与选型建议

如果希望以最少的手工操作完成整套部署，优先考虑 Wasp CLI 的 Fly.io 部署——wasp deploy fly launch <app-name> <region>一条命令即可完成服务端、客户端与数据库的创建和部署，并在项目根目录生成可版本化的fly-server.toml/fly-client.toml，后续用wasp deploy fly deploy即可增量更新。

如果你的目标平台不在上述列表中也不必担心——只要托管商支持 Docker 镜像与静态文件托管，就能按本文第一部分「通用四步」的流程完成部署。本文所有操作均基于本仓库 version-0.16 PaaS 部署文档 与仓库内的示例配置（如 examples/waspello/ 的 Fly 配置文件），可随时回到仓库对照原文与源码进一步钻研。

【免费下载链接】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