手把手手动部署 Wasp 全栈应用构建产物、服务端环境变量与 Fly.io / Netlify / Railway / Heroku 全流程实战【免费下载链接】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 全栈框架React Node.js Prisma的手动部署实战指南围绕wasp build生成部署产物再到 API Server、Web Client、PostgreSQL 数据库三个组成部分的分别部署覆盖 Fly.io、Netlify、Railway、Heroku 四个主流平台的逐步操作。读完本文你将掌握 Wasp 应用构建 → 配置环境变量 → 部署前后端与数据库 → 后续重部署的完整方法论并能据此将应用部署到任意支持 Wasp 构建格式的托管平台。部署前的核心认知Wasp 应用由三部分组成Wasp 应用是一个全栈应用从部署视角看它由三个相互独立、可以分开部署到不同平台的组成部分构成见 部署概览文档组成部分技术形态典型托管方式API Server后端Node.js 服务以 Docker 镜像形式分发Fly.io、Railway、Heroku 等容器平台Web Client前端构建后的纯静态文件Netlify、Cloudflare Pages 等静态托管数据库PostgreSQLFly.io Postgres、Railway Postgres、Neon 等正因为三者解耦你可以自由组合例如客户端放 Netlify、服务端放 Fly.io、数据库用 Neon。手动部署的本质就是分别处理好这三块并用环境变量把它们粘起来。第一步用wasp build生成部署代码无论最终部署到哪个平台第一步都是相同的——在项目根目录执行wasp build该命令会在项目的.wasp/build/目录中生成整个应用的部署代码包含服务端代码与用于构建服务端镜像的Dockerfile前端工程.wasp/build/web-app/需要进一步构建出静态文件数据库迁移文件与 Prisma 相关产物。:::caution 生产环境必须使用 PostgreSQL Wasp 的默认数据库是 SQLite但使用 SQLite 时无法执行wasp build构建生产代码。在部署到生产环境之前必须先从 SQLite 迁移到 PostgreSQL否则构建会直接失败。 :::第二步部署 API Server后端.wasp/build目录中有一个定义好的Dockerfile它用于构建服务端镜像。部署时把该镜像推到任意支持 Docker 的托管平台并在平台上正确配置环境变量即可。所有必需的环境变量如下。服务端必需环境变量以下是 Wasp 服务端运行时查找的全部环境变量。其中变量名在 Wasp 生成器中是硬编码的见 ServerGenerator/Common.hsclientUrlEnvVarName WASP_WEB_CLIENT_URL serverUrlEnvVarName WASP_SERVER_URL ... PORT变量名必填性说明与示例DATABASE_URL✅ 必填应用要使用的 PostgreSQL 连接串例如postgresql://mydbuser:mypasslocalhost:5432/nameofmydbWASP_WEB_CLIENT_URL✅ 必填前端部署后的 URL例如https://app-name.netlify.app。服务端需要它来正确配置跨域CORS/Same-Origin Policy头WASP_SERVER_URL✅ 必填服务端自身的 URL例如https://app-name.fly.dev。使用 Google、GitHub 等 OAuth 登录时服务端需要它来正确构造重定向地址JWT_SECRET使用 Wasp Auth 时必填随机字符串至少 32 个字符。仅在使用 Wasp 的auth功能时才需要PORT选填服务端监听请求的 HTTP 端口默认3001外部认证提供方的额外环境变量如果应用使用了 Wasp 支持的外部认证方式如 Google 社交登录 或 GitHub 社交登录还必须额外设置这些认证方式各自要求的密钥类环境变量如GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET等。这一点在手动部署到任何平台时都适用下文各平台的部署步骤会反复提醒。环境变量的设置机制因平台而异Fly.io 用flyctl secrets、Heroku 用heroku config:set、Railway 在 Dashboard 的 Variables 页配置但变量名与含义完全一致。第三步部署 Web Client前端后端就绪后构建前端。前端构建产物只是一堆静态文件因此可以部署到 Netlify、Cloudflare 等任意静态托管平台。构建 Web Client进入前端工程目录并执行构建命令cd .wasp/build/web-appnpm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你先前部署好的 Wasp 服务端 URL。构建完成后静态文件输出到.wasp/build/web-app/build/目录——部署该目录的内容即可。:::caution 客户端环境变量 如果项目里手动定义过其他客户端环境变量以REACT_APP_开头的变量它们在构建时被内联进静态文件必须在上面这条构建命令中一并传入例如REACT_APP_ANOTHER_VARsomevalue npm run build。每次重新构建都要带上否则这些变量会丢失。 :::第四步部署 PostgreSQL 数据库数据库部分没有任何 Wasp 专属要求任何 PostgreSQL 实例都可以只要把正确的DATABASE_URL配置给服务端并确保数据库对服务端网络可达即可。你可以使用托管平台的数据库服务下文 Fly.io、Railway、Heroku 都会自动配置DATABASE_URL也可以使用外部数据库服务。平台实战一Fly.io服务端 数据库Fly.io 提供多种免费额度非常适合部署第一个 Wasp 应用。本小节展示在 Fly.io 上部署服务端并创建数据库的完整流程。如果希望用一条命令自动完成下面的全部工作可以使用 Wasp CLI 部署它会自动部署服务端、客户端并创建数据库。前置准备注册 Fly.io 账号并安装flyctlCLI登录用flyctl auth whoami检查登录状态未登录则执行flyctl auth login说明Fly.io 同时支持本地构建与远程构建 Docker 镜像为了可复现性下文统一使用远程构建器fly在多数系统上是flyctl的软链接二者可互换使用。初始化 Fly.io 应用每个 Wasp 应用只需一次先确保已完成wasp build然后进入构建目录cd .wasp/build运行启动命令创建新应用并生成fly.tomlflyctl 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 初始化失败怎么办 如果初始化新应用失败先执行flyctl apps destroy app-name再重试。Fly 不允许创建多个同名应用。数据库部署成功后可以在 Fly.io dashboard 中看到它如下图所示:::接下来把fly.toml复制回 Wasp 项目根目录妥善保存后面重部署会用到cp fly.toml ../../然后为服务端设置其余环境变量flyctl secrets set PORT8080 flyctl secrets set JWT_SECRET随机字符串_至少32字符 flyctl secrets set WASP_WEB_CLIENT_URL客户端将部署到的URL flyctl secrets set WASP_SERVER_URL服务端将部署到的URL:::note 如果暂时还不知道客户端 URL不用担心可以在部署完客户端之后再设置WASP_WEB_CLIENT_URL。 :::使用外部认证Google / GitHub 等时还要按上文说明补充对应密钥变量。若想确认 secrets 是否设置正确运行flyctl secrets list注意出于安全考虑输出的是哈希后的密文。仓库中 ask-the-documents 示例的 fly-server.toml 展示了一份真实的 Fly 配置app ask-the-documents-server、internal_port 8080、force_https true、min_machines_running 1以及1gb内存的共享 CPU 虚拟机——可作为手动修改fly.toml的参考。部署到 Fly.io仍在.wasp/build/目录下执行flyctl deploy --remote-only --config ../../fly.toml这会构建并部署 Wasp 后端到https://app-name.fly.dev。之后可部署客户端再把客户端 URL 通过flyctl secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client补上客户端建议用 Netlify 托管也可用任意静态托管。常用运维命令flyctl logs flyctl secrets list flyctl ssh console重新构建后的重部署每次执行wasp build都会删除并重建.wasp/build/目录其中之前生成的fly.toml也会一并消失。有三种方式应对把fly.toml纳入版本管理如复制到 Wasp 项目根目录之后用flyctl deploy --config path显式指定配置路径就像上文那样在运行wasp build之前备份fly.toml构建完再复制回.wasp/build/中——此时目录内已存在fly.toml无需再指定--config path用flyctl config save -a app-name从 Fly.io 远端状态重新生成fly.toml。平台实战二Netlify客户端Netlify 对许多场景免费适合托管 Wasp 前端。前置准备注册 Netlify 账号并安装 Netlify CLI用netlify status检查登录状态未登录则执行netlify login。部署步骤确保已完成wasp build构建前端cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build首次部署交互式向导会询问创建新应用还是使用已有应用、归属于哪个团队等netlify deploy发布到生产环境netlify deploy --prod完成后客户端即可在https://app-name.netlify.app访问。:::note 务必把该 URL 设置为服务端托管环境如 Fly.io 或 Heroku中的WASP_WEB_CLIENT_URL环境变量否则前后端跨域配置会不正确。 :::平台实战三Railway服务端 客户端 数据库Railway 可以一站式托管数据库、服务端和客户端且免费试用或满足条件时可免费使用。前置准备在项目目录运行wasp build完成构建注册 Railway 账号用 GitHub 账号注册有机会获得免费额度安装 Railway CLI运行railway login浏览器会自动打开完成认证。创建 Railway 项目进入 Railway dashboard点击New Project从下拉菜单选择Provision PostgreSQL初始化完成后点击右上角New按钮并选择Empty Service进入该服务的Settings General把名字改为server再创建一个空服务并命名为client。部署到 Railway生成域名进入server与client两个服务的Settings页分别点击Generate Domain生成域名复制保存稍后要用。部署服务端进入应用的构建目录cd .wasp/build把构建产物关联到 Railway 项目railway link在 Railway Dashboard 的Settings Variables页配置环境变量点击Variable reference并选择DATABASE_URLRailway 会自动填充正确的值添加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当提示Select Service时选择server。Railway 会自动识别 Dockerfile 并部署服务端。部署客户端进入前端构建目录cd web-app用server域名作为 API 地址构建生产版本npm install REACT_APP_API_URLurl_to_wasp_backend npm run build把该前端目录也关联到项目railway link配置 Railway 静态托管把web-app下的build目录复制为distcp -r build dist再创建两个文件Dockerfile基于静态文件服务器镜像并把 SPA 路由回退到index.htmlFROM pierrezemb/gostatic CMD [ -fallback, index.html ] COPY ./dist/ /srv/http/.dockerignorenode_modules/:::info 每次wasp build后都要重做 由于wasp build会删除.wasp/build/web-app目录以上创建dist、Dockerfile、.dockerignore的步骤每次重新构建后都需要重复。可将下面这段脚本保存为项目根目录的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_URLurl_to_wasp_backend ./deploy_client.sh:::在Variables页把PORT环境变量设为8043部署客户端提示Select Service时选择clientrailway up部署完成后回到 Railway dashboard 即可看到 PostgreSQL、Server、Client 三个服务。更新与重部署运行wasp build重新构建应用在.wasp/build目录运行railway up部署服务端在.wasp/build/web-app目录重复客户端的全部步骤部署客户端。平台实战四Heroku服务端 数据库:::note Heroku 已于 2022 年 11 月 28 日终止免费套餐。对于第一个应用建议优先考虑 Fly.io 等替代方案。 :::前置准备需要 Heroku 账号、herokuCLI 与dockerCLI。用heroku whoami检查登录状态未登录则执行heroku login。初始化 Heroku 应用每个 Wasp 应用只需一次创建新应用或复用已有应用heroku create app-name创建并挂载 PostgreSQL 数据库除非已有外部数据库heroku addons:create --app app-name heroku-postgresql:mini:::caution Heroku 已无免费方案mini是其最便宜的数据库实例费用为每月 5 美元。创建后 Heroku 会自动设置DATABASE_URL若使用外部数据库则需自行配置PORT也由 Heroku 提供。 :::剩下的三个环境变量手动设置heroku config:set --app app-name JWT_SECRET随机字符串_至少32字符 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:::note 暂时不知道客户端 URL 也没关系可在部署完客户端后再设置WASP_WEB_CLIENT_URL。 :::部署到 Heroku完成wasp build后进入.wasp/build/目录假设当前在 Wasp 项目根目录cd .wasp/build登录 Heroku 容器镜像仓库heroku container:login构建 Docker 镜像并推送到 Herokuheroku container:push --app app-name web注意此时应用尚未部署。首次推送耗时较长没有缓存的 Docker 层。:::note Apple SiliconM1/M2 等用户 需要构建非 Arm 架构镜像不能用heroku container:push改为docker buildx build --platform linux/amd64 -t app-name . docker tag app-name registry.heroku.com/app-name/web docker push registry.heroku.com/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:::note 在 Heroku 上使用pg-boss执行器 若要部署使用 Jobs后台任务 且执行器为pg-boss的应用还需要额外设置环境变量PG_BOSS_NEW_OPTIONS为{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}。原因是 pg-boss 依赖的pg扩展默认不会通过 SSL 连接而 Heroku 强制要求 SSL且其证书为自签名证书需要显式关闭校验。 :::进阶用 Wasp CLI 一键部署与定制 Dockerfile手动部署流程清晰可控但如果你想省去上述所有手工步骤Wasp 还提供单命令部署推荐用于 Fly.io见 Wasp CLI 部署文档wasp deploy fly launch my-wasp-app mia该命令在底层等价于依次执行setup、create-db、deploy三步并在项目根目录生成fly-server.toml与fly-client.toml两个配置文件建议纳入版本管理便于日后一条命令重部署。另外如果你想定制服务端镜像的构建过程Wasp 默认生成的是多阶段 Dockerfile负责构建服务端镜像并自动执行待运行的数据库迁移。你可以在 Wasp 项目根目录放一个自己的DockerfileWasp 会把它追加到默认多阶段 Dockerfile 的末尾——由于 Docker 中后定义者生效你可以覆盖或续写任意构建阶段。注意最终阶段必须提供ENTRYPOINT否则改动不生效。可用wasp dockerfile预览合并后的完整 Dockerfile详见 部署概览文档。小结Wasp 手动部署的完整链路可以概括为四步wasp build生成部署产物 → 通过 Docker 镜像部署 Node.js 服务端配置DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET、PORT等环境变量→ 用REACT_APP_API_URL构建并托管静态前端 → 提供可达的 PostgreSQL 数据库。这套流程不绑定任何单一云厂商——Fly.io、Netlify、Railway、Heroku 之外凡是支持 Docker 容器与静态托管的平台都可以按同样的模式接入。【免费下载链接】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），仅供参考
