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/waspWasp 构建产物是平台无关的可部署代码 Docker 镜像 静态文件因此你可以把生成的 Wasp 应用部署到任何支持 Node.js 服务、静态文件托管与 PostgreSQL 数据库的 PaaS 平台。本文以 web/versioned_docs/version-0.18/deployment/deployment-methods/paas.md 为核心完整讲解通用四步部署流程并逐步演示在 Fly.io服务端 数据库、Railway全栈、Heroku服务端 数据库、Netlify 与 Cloudflare Pages客户端静态托管上的部署步骤、环境变量配置与 CI 自动化方案。读完本文你将掌握 Wasp 应用生产部署的完整链路并能根据需求选择最合适的 PaaS 组合。通用部署四步走无论选择哪家 PaaS 提供商部署一个 Wasp 应用本质上都归结为四件事生成可部署代码wasp build。部署 API 服务端后端。部署 Web 客户端前端。部署并持续运行一个 PostgreSQL 数据库。1. 生成可部署代码在 Wasp 项目根目录运行wasp build该命令会把整个应用的可部署代码生成到.wasp/build/目录在 version-0.18 这个版本中输出目录为.wasp/build/较新版本已改为.wasp/out/。构建产物包含三部分服务端一个用于构建服务端镜像的 Dockerfile位于.wasp/build/根目录客户端构建后的静态文件位于.wasp/build/web-app/build/数据库对应的 Prisma schema 与迁移文件随服务端 Docker 镜像一同打包。# 确认构建产物结构 ls .wasp/build # Dockerfile server/ web-app/ db/ ...⚠️ 生产环境必须使用 PostgreSQL如果应用使用的是默认的 SQLite 数据库wasp build将无法成功构建。在部署到生产环境前必须先从 SQLite 迁移到 PostgreSQL。从源码看服务端 Dockerfile 采用多阶段构建base → server-builder → server-production模板位于 waspc/data/Generator/templates/Dockerfile在server-builder阶段安装依赖并执行npx prisma generate在server-production阶段只拷贝构建产物bundle、node_modules、db/并以npm run start-production作为容器入口EXPOSE ${PORT}表明容器对外暴露的端口由PORT环境变量控制这与下文各平台设置PORT8080的做法直接对应。2. 部署 API 服务端.wasp/build目录中有一个定义服务端镜像的 Dockerfile。要运行生产环境服务端需要把这个 Docker 镜像部署到托管平台并正确配置所需的环境变量。通常使用平台的控制台 UI 或 CLI 工具来设置这些环境变量。必须先核对服务端必需的环境变量并确保全部配置到位。下面各平台章节会给出对应的设置命令。3. 部署 Web 客户端构建 Web 客户端的方式是先进入.wasp/build/web-app目录再执行cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是之前已部署的 Wasp 服务端地址。构建产物是纯静态文件位于.wasp/build/web-app/build/可以部署到任意静态托管平台如 Netlify、Cloudflare Pages。客户端环境变量通过构建命令注入如果在项目中定义了其他客户端环境变量必须一并加在上述构建命令中。Wasp 会在构建期间把import.meta.env.REACT_APP_*替换为实际值因此永远不要把密钥类信息放进客户端环境变量——它们会随静态文件公开可见。不要指望在托管平台给静态文件注入客户端环境变量静态文件构建后是死的宿主环境变量对它们无效服务端环境变量则相反应在宿主上设置。4. 部署数据库任何 PostgreSQL 数据库都可以只要满足两个条件向服务端提供正确的DATABASE_URL环境变量确保数据库能被服务端访问。各平台数据库方案汇总平台是否托管数据库说明Fly.io✅ 是fly launch时选择 PostgreSQL自动设置DATABASE_URLRailway✅ 是新建项目时选择 Deploy PostgreSQLHeroku✅ 是heroku addons:create heroku-postgresql:essential-0自动设置DATABASE_URLNetlify❌ 否仅托管客户端静态文件Cloudflare❌ 否仅托管客户端静态文件推荐的 CLI 一键部署方式wasp deploy在各平台章节开始前先说明一点Wasp 提供了更省事的 CLI 自动化部署命令wasp deploy它把手动部署流程自动化是官方推荐方式。基本用法为wasp deploy provider launch my-wasp-appwasp deploy会在提供商侧创建全部所需服务、构建 Wasp 应用并完成部署。例如部署到 Fly.iowasp deploy fly launch my-wasp-app mia该命令会基于应用名my-wasp-app创建三个独立应用my-wasp-app-client、my-wasp-app-server、my-wasp-app-db并在项目根目录生成fly-server.toml与fly-client.toml两个配置文件应纳入版本控制方便以后一条命令重新部署。其他服务端密钥可用wasp deploy fly cmd secrets set --contextserver ...追加。如果你的提供商/平台恰好支持 CLI 自动化Fly.io、Railway 均支持优先使用它下面的手动步骤用于理解底层机制或在你需要完全掌控部署细节时使用。部署到 Fly.io服务端 数据库Fly.io 提供容器化应用托管本节演示如何把服务端部署上去并为其配置数据库。前提条件注册 Fly.io 账号安装flyCLI用flyCLI 登录。检查是否已登录fly auth whoami未登录则执行fly auth login创建 Fly.io 应用每个 Wasp 应用只需执行一次。如果还没有想复用的 Fly.io 应用先构建应用然后进入.wasp/build/目录cd .wasp/build运行 launch 命令来创建新应用并生成fly.toml文件fly 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——因为还需要设置多个环境变量。如果数据库/应用创建失败怎么办先执行fly apps destroy app-name再重试。Fly 不允许创建同名应用。把生成的fly.toml复制到 Wasp 项目根目录保存避免被下次wasp build清掉cp fly.toml ../../仓库中的 examples/waspello/fly-server.toml 展示了此类配置的典型形态internal_port 8080、force_https true、单实例shared1 CPU / 1GB 内存与下文PORT8080的设置一一对应。设置服务端环境变量接下来为服务端代码添加几个必需的环境变量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_deployedPORT8080必须与fly.toml中http_service.internal_port一致JWT_SECRET至少 32 字符的随机字符串用于签发/校验会话 JWT泄露它意味着任何人都能伪造会话WASP_WEB_CLIENT_URL客户端部署后的地址决定 CORS 与回调地址WASP_SERVER_URL服务端自己的公开地址。还不知道客户端地址不必担心可以先部署客户端之后再执行fly secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client补上。如果应用使用了 Wasp 支持的外部认证方式如 Google、GitHub OAuth还需要额外设置这些认证方式要求的环境变量。核对密钥是否设置成功fly secrets list注意出于安全考虑列表中显示的是密钥的哈希版本。部署到 Fly.io仍在.wasp/build/目录下执行fly deploy --remote-only --config ../../fly.toml这会构建并把 Wasp 应用的后端部署到 Fly.io服务地址为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都会清空.wasp/build/目录之前放在里面的fly.toml会丢失。目前有三种应对方式把fly.toml放到版本控制目录如 Wasp 项目根目录然后在fly deploy --config path中引用它即上面示例的做法备份fly.toml到别处wasp build后再复制回.wasp/build/——当fly.toml存在于.wasp/build/时无需指定--config path用fly config save -a app-name从 Fly.io 远程状态重新生成fly.toml。部署到 Railway服务端 客户端 数据库Railway 可以在一个项目里同时承载客户端、服务端与 PostgreSQL 数据库是全栈单平台的典型选择。前提条件在项目目录运行wasp build完成构建注册 Railway 账号安装 Railway CLI运行railway login浏览器会打开进行身份认证。创建项目打开 Railway dashboard点击New Project从下拉菜单中选择Deploy PostgreSQL项目创建后点击右上角Create按钮选择Empty Service点击新服务把名字改为server再创建一个空服务命名为client点击顶部的Deploy按钮部署这些变更。部署应用到 Railway配置域名服务端和客户端服务都需要域名进入server实例的Settings标签页点击Generate Domain端口填8080点击Generate Domain对client服务重复同样操作复制两个域名后面会用到。部署服务端进入.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 字符的随机字符串。同样地使用外部认证时记得追加对应的认证环境变量。推送并部署项目railway up --ci使用--ci标志可把日志输出限制为只显示构建过程。Railway 会自动定位.wasp/build中的 Dockerfile 并部署服务端。部署客户端进入前端构建目录.wasp/build/web-appcd web-app用server域名作为REACT_APP_API_URL构建生产版本npm install REACT_APP_API_URLurl_to_wasp_backend npm run build把客户端构建目录链接到client服务cd build railway link部署客户端构建产物到 Railwayrailway up --ci提示选择服务时选择client。Railway 会检测到index.html把客户端作为静态站点部署。回到 Railway dashboard点击项目即可看到三个已部署的服务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 适合托管服务端与 PostgreSQL 数据库客户端仍需部署到静态托管平台。前提条件需要 Heroku 账号、herokuCLI 和dockerCLI。确认已登录heroku whoami未登录则heroku login创建 Heroku 应用每个 Wasp 应用只需执行一次。创建新应用除非想部署到已有应用heroku create app-name创建并挂载数据库除非已有外部 PostgreSQL 数据库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_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暂时不知道客户端地址也没关系部署完客户端后再补WASP_WEB_CLIENT_URL即可。部署 Heroku 应用构建应用后进入.wasp/build/目录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此时应用尚未部署首次推送因无缓存层会耗时较长。发布镜像并重启应用heroku container:release --app app-name web后端即部署完成地址形如https://app-name-XXXX.herokuapp.com。查询确切地址heroku info --app app-name查看日志heroku logs --tail --app app-name 使用pg-boss执行器时的特殊配置如果应用使用了以pg-boss为执行器的 Jobs后台任务部署到 Heroku 时需要额外设置环境变量PG_BOSS_NEW_OPTIONS为{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}。原因pg-boss 依赖的pg扩展默认不走 SSL 连接而 Heroku 要求 SSL 且使用自签名证书。可参阅Jobs 文档了解更多。部署到 Netlify客户端Netlify 是静态托管方案很多场景免费。需要 Netlify 账号与 Netlify CLI。检查登录状态npx netlify-cli status未登录则npx netlify-cli login先构建 Wasp 应用然后构建客户端 Web 应用命令见上文部署 Web 客户端一节。部署客户端npx netlify-cli deploy仔细跟随交互提示决定是新建应用还是复用已有应用、选择部署到哪个 team 等。最后正式发布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正确地把 URL 重定向到index.html——这对 Wasp 至关重要因为 Wasp 客户端是单页应用SPA需要客户端路由接管页面跳转。如果改用其他方式如 CI部署务必让 Netlify 读取到该netlify.toml或手动配置 URL 重定向。通过 GitHub Actions 自动化部署创建.github/workflows/deploy.yaml文件文件名可改但类型不能变实现每次 push 到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/checkoutv2 - name: Setup Node.js id: setup-node uses: actions/setup-nodev4 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服务端地址一般只有在后端部署完成后才可用后端未就绪时可以跳过但要意识到依赖后端的功能会不可用。拿到这三个值后把它们配置到 GitHub Repository Secrets 中。部署到 Cloudflare Pages客户端Cloudflare 提供免费静态托管服务 Cloudflare Pages。需要 Cloudflare 账号与 Wrangler CLI。登录npx wrangler login先构建 Wasp 应用再构建客户端 Web 应用。进入.wasp/build/web-app目录后执行npx wrangler pages deploy ./build --commit-dirtytrue --branchmain跟随交互提示新建应用还是复用已有应用。客户端将上线于https://app-name.pages.dev。注意务必把https://app-name.pages.dev设置为服务端托管环境中的WASP_WEB_CLIENT_URL环境变量。SPA 路由Cloudflare 会自动把所有路径重定向到index.html。这对 Wasp 客户端SPA至关重要客户端路由需要在浏览器端接管页面切换。通过 GitHub Actions 自动化部署创建.github/workflows/deploy.yaml实现 push 到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/checkoutv2 - name: Setup Node.js id: setup-node uses: actions/setup-nodev4 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 控制台获取令牌需要Cloudflare Pages: Read和Cloudflare Pages: Edit权限CLIENT_CLOUDFLARE_APP_NAMECloudflare Pages 应用名可通过npx wrangler pages project create app-name创建WASP_SERVER_URL服务端地址一般在后端部署完成后才有可跳过但依赖后端的功能会不可用。同样把这些值配置到 GitHub Repository Secrets 中。各平台选型速览与通用注意事项平台托管能力关键 CLI/命令必设服务端环境变量Fly.io服务端 数据库fly launch --remote-only、fly deploy --remote-only、fly secrets setPORT、JWT_SECRET、WASP_WEB_CLIENT_URL、WASP_SERVER_URLRailway服务端 客户端 数据库railway link、railway up --ciDATABASE_URL引用、JWT_SECRET、WASP_WEB_CLIENT_URL、WASP_SERVER_URLHeroku服务端 数据库heroku container:push、heroku container:releaseJWT_SECRET、WASP_WEB_CLIENT_URL、WASP_SERVER_URLDATABASE_URL、PORT自动设置Netlify客户端静态npx netlify-cli deploy --prod只需在服务端设置WASP_WEB_CLIENT_URL指向 Netlify 域名Cloudflare Pages客户端静态npx wrangler pages deploy ./build只需在服务端设置WASP_WEB_CLIENT_URL指向 Pages 域名通用注意事项总结服务端环境变量生产环境会忽略.env.server必须通过托管平台的机制fly secrets set、Railway Variables 面板、heroku config:set等设置。必设项包括DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET外部认证OAuth等场景还需追加对应变量。客户端环境变量生产环境会忽略.env.client必须在构建客户端时以命令行前缀注入REACT_APP_*并且每次重新部署都要重新提供。切勿在其中存放密钥。SPA 路由客户端是单页应用静态托管方必须把所有路径重定向到index.htmlNetlify 用 Wasp 生成的netlify.tomlCloudflare Pages 自动处理。构建产物的可丢弃性wasp build会清空.wasp/build/所以需要长期保留的配置如fly.toml要存到版本控制目录或另行备份。数据库连接任何 PostgreSQL 均可用前提是DATABASE_URL正确且数据库可从服务端访问涉及 SSL如 Heroku pg-boss时按平台要求处理连接配置。如果上述列表中找不到你心仪的 PaaS 提供商也不要紧——只要它支持 Wasp 的构建格式Node.js 服务、静态文件、PostgreSQL你就可以按通用部署四步走完成部署。【免费下载链接】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），仅供参考