Wasp 手动部署实战wasp build 构建产物、核心环境变量与 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 官方文档version-0.14 版Deploying Manually编写系统讲解 Wasp 应用脱离托管部署方案后的手动部署全流程如何用wasp build生成可部署产物、API Server 与 Web Client 各自需要什么环境变量、PostgreSQL 数据库如何接入并给出 Fly.io、Netlify、Railway、Heroku 四个平台完整的逐条命令实操。读完本文你可以把任意 Wasp 应用部署到任何支持 Wasp 构建格式的托管平台。部署模型总览四个核心步骤Wasp 应用的手动部署可以归结为以下四步生成可部署代码Generating deployable code部署 API Server后端部署 Web Client前端部署一个 PostgreSQL 数据库并让它持续运行。只要你的托管平台能够承载 Wasp 的构建产物形态Docker 镜像 静态文件无论它是否在官方指南列表里你都可以按这个模型完成部署。列表只是“有逐条步骤指南”的平台而非“支持的平台”。1. 生成可部署代码wasp build在项目根目录执行wasp build该命令会在.wasp/build/目录中生成整个应用的可部署代码包括后端的 Dockerfile 和前端的web-app/工程。重要限制生产环境必须使用 PostgreSQL。如果你当前使用 SQLiteWasp 的默认数据库wasp build会拒绝构建。你需要先按照官方文档 从 SQLite 迁移到 PostgreSQL 完成切换再进入部署流程。2. 部署 API Server后端.wasp/build/目录中包含一个定义后端镜像的 Dockerfile。部署后端就是把这个 Docker 镜像推到托管平台运行并确保平台侧的环境变量配置正确具体设置机制因平台而异。后端环境变量清单变量是否必需说明DATABASE_URL必需你的 PostgreSQL 数据库连接 URL例如postgresql://mydbuser:mypasslocalhost:5432/nameofmydbWASP_WEB_CLIENT_URL必需前端应用将要运行的 URL如https://app-name.netlify.app。服务端需要它来正确配置 CORSSame-Origin Policy响应头WASP_SERVER_URL必需服务端自身运行的 URL如https://app-name.fly.dev。OAuth 登录Google、GitHub 等跳转回来时服务端需要它做正确重定向JWT_SECRET使用 Wasp Auth 时必需仅当应用使用了 Wasp 的auth特性时才需要。设置为一个至少 32 字符长的随机字符串可用在线随机字符串生成工具生成PORT可选服务端 HTTP 监听端口默认3001另外如果你的应用使用了 Wasp 支持的外部认证方式如 Google、GitHub 社交登录还必须额外配置这些认证方式各自要求的环境变量——这是部署时最容易遗漏的一项。从源码结构看JWT_SECRET并非装饰性配置生成的后端代码中SDK 的 JWT 模块 会执行const JWT_SECRET new TextEncoder().encode(config.auth.jwtSecret);即将该变量编码为字节后用于会话令牌的签发与校验。缺少它意味着所有基于会话的鉴权都会失效。3. 部署 Web Client前端前端构建步骤来自文档内嵌片段 _building-the-web-client.md进入构建出的前端工程目录cd .wasp/build/web-app执行安装与构建并注入指向后端的 API 地址npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend就是你之前部署的 Wasp 服务端 URL。注意如果你在项目中手动定义了其他客户端环境变量参见 客户端环境变量说明必须在上面的 build 命令中一并传入否则构建产物中不会包含这些值。构建结果落在.wasp/build/web-app/build/目录。由于产物只是一组静态文件你可以把它部署到任何静态托管平台Netlify、Cloudflare 等——只需部署.wasp/build/web-app/build/目录的内容即可。4. 部署数据库任何 PostgreSQL 实例都可以前提有两个通过DATABASE_URL把正确的连接串交给服务端保证数据库可以从服务端所在网络访问到。平台一Fly.ioserver databaseFly.io 提供免费额度适合部署你的第一个 Wasp 应用。前置要求Fly.io 账号与flyctlCLIfly在多数系统是flyctl的符号链接两者可互换。为简单与可复现指南默认使用 Fly.io 的远程构建。登录检查flyctl auth whoami # 检查登录状态 flyctl auth login # 未登录时执行创建 Fly.io 应用每个 Wasp 应用只需一次先完成wasp build然后定位到.wasp/build/目录cd .wasp/build运行 launch 命令创建新应用并生成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后续所有附加问题也选 no——因为你还差几个环境变量没配。如果创建应用/数据库失败先执行flyctl apps destroy app-name再重试——Fly 不允许创建重名的应用。数据库部署成功时你会在 Fly.io 控制台中看到对应的 PostgreSQL 实例见文首第一张截图。把fly.toml备份到 Wasp 项目根目录cp fly.toml ../../接着为服务端代码补充环境变量flyctl secrets set PORT8080 flyctl secrets set JWT_SECRETrandom_string_at_least_32_characters_long flyctl secrets set WASP_WEB_CLIENT_URLurl_of_where_client_will_be_deployed flyctl secrets set WASP_SERVER_URLurl_of_where_server_will_be_deployed如果前端 URL 还不确定不用慌——等前端部署完再补设WASP_WEB_CLIENT_URL即可。若使用外部认证还需按上文补充其专属环境变量。可用flyctl secrets list校验 secrets 是否添加成功出于安全列表中显示的是哈希值而非明文。部署到 Fly.io仍在.wasp/build/目录内执行flyctl deploy --remote-only --config ../../fly.toml该命令会构建并把 Wasp 后端部署到https://app-name.fly.dev。随后部署前端推荐 Netlify并执行flyctl secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client补上客户端 URL。日常运维常用命令flyctl logs # 查看日志 flyctl secrets list # 查看密钥 flyctl ssh console # SSH 进入容器重新构建后如何恢复 fly.toml再次执行wasp build会删除.wasp/build/目录连同其中的fly.toml一起消失。三种应对方式版本化保存推荐把fly.toml放在 Wasp 项目目录中部署时用flyctl deploy --config path引用它构建前备份wasp build之前备份fly.toml构建后再拷回.wasp/build/。文件存在于该目录时无需再指定--config从远端状态重新生成flyctl config save -a app-name从 Fly.io 远端拉回当前配置。平台二NetlifyclientNetlify 是静态托管方案很多使用场景免费。前置要求Netlify 账号 Netlify CLI。确认登录状态netlify status未登录则netlify login。确保已执行wasp build然后按上文“部署 Web Client”一节构建前端。首次预览部署netlify deploy按提示操作选择创建新应用还是使用已有应用、应用归属的团队等。生产部署netlify deploy --prod客户端即上线于https://app-name.netlify.app。最后一步把这个 URL 设置到服务端所在环境Fly.io、Heroku 等的WASP_WEB_CLIENT_URL环境变量中否则 CORS 配置不生效。平台三Railwayserver client databaseRailway 可以承载数据库、服务端与客户端即整个应用。它提供限时免费或有资格条件下的免费使用以官方定价页为准。前置准备在项目根目录执行wasp build确保应用已构建创建 Railway 账号用 GitHub 账号注册以获得免费额度资格安装 Railway CLI执行railway login浏览器会打开完成认证。创建新项目进入 Railway Dashboard点击New Project从下拉菜单选择Provision PostgreSQL初始化完成后右键点击右上角New按钮选择Empty Service该服务初始化后进入Settings General将名字改为server见文首第二张截图再创建第二个 Empty Service命名为client。配置域名服务端与客户端都需要域名分别在server与client实例的Settings标签页点击Generate Domain并记下这两个域名后续配置环境变量要用。部署服务端进入构建目录cd .wasp/build把当前目录链接到刚才创建的 Railway 项目railway link在 Railway Dashboard 的Settings Variables中配置环境变量点击Variable reference选择DATABASE_URL自动填充为 Postgres 服务的正确值添加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 并部署服务端。从源码结构看这套手动流程与 Wasp CLI 的 Railway 部署逻辑同构CLI 的实现 setup.ts 中的setup函数正是按“数据库服务 → 客户端服务 → 服务端服务”的顺序创建三者且每步都有幂等检查服务已存在时跳过例如打印Postgres service already exists. Skipping database creation.并先调用ensureWaspProjectIsBuilt确认项目已构建——与手动部署的前提一致。部署客户端进入前端构建目录cd web-app使用 server 域名作为REACT_APP_API_URL构建生产前端npm install REACT_APP_API_URLurl_to_wasp_backend npm run build将该前端目录也链接到项目railway link配置 Railway 的静态托管把web-app/build复制为web-app/distcp -r build dist然后创建两个文件DockerfileFROM pierrezemb/gostatic CMD [ -fallback, index.html ] COPY ./dist/ /srv/http/.dockerignorenode_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_URLurl_to_wasp_backend ./deploy_client.sh在Variables标签页将客户端的PORT环境变量设为8043gostatic 镜像的监听端口。部署客户端railway up提示Select Service时选择client。完成后Railway Dashboard 中应能看到项目下的三个服务PostgreSQL、Server、Client。更新与重新部署代码变更后执行wasp build重新构建在.wasp/build目录执行railway up服务端在.wasp/build/web-app目录重做上述客户端全部步骤。平台四Herokuserver databaseHeroku 曾提供免费应用但自 2022-11-28 起已取消免费层因此官方建议首个应用改用 Fly.io。前置要求Heroku 账号、herokuCLI 与dockerCLI。用heroku whoami检查登录未登录则heroku login。创建 Heroku 应用每个 Wasp 应用只需一次heroku create app-name没有外部 PostgreSQL 时在 Heroku 上创建并挂载一个数据库heroku addons:create --app app-name heroku-postgresql:miniHeroku 已无免费计划mini是其最便宜的数据库实例约 $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客户端 URL 未知时可以先跳过WASP_WEB_CLIENT_URL前端部署后再补。部署到 Heroku完成wasp build后cd .wasp/build # 假设当前在 Wasp 项目根目录 heroku container:login # 登录 Heroku Container Registry构建并推送镜像heroku container:push --app app-name web此时应用尚未上线。该步骤尤其首次无缓存的 Docker 层可能耗时较长。Apple Silicon 用户注意需要构建非 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查看确切 URL用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 数据库而 Heroku 强制要求 SSL同时 Heroku 使用自签名证书必须允许该情况。其他平台与 CLI 快捷方式Koyeb社区有针对 Wasp 整应用server、client、database部署到 Koyeb 的官方教程注意其编写针对的是 Wasp v0.13。Wasp CLI如果不想手工执行上述任何平台流程可以使用 Wasp CLI 一键完成——CLI 部署文档中wasp deploy会自动部署服务端与客户端、创建数据库并提供单命令重新部署更新能力该文档同时说明 Fly.io 每月提供 $5 免费额度。小结Wasp 手动部署的本质非常清晰wasp build产出“Dockerfile 静态站点”两种标准形态你只需把前者当作一个普通 Node 服务、后者当作一个静态站点分别部署到任意托管平台再保证五类环境变量DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET、PORT与一个可达的 PostgreSQL 就位即可。官方为 Fly.io、Netlify、Railway、Heroku 提供了逐条命令的参考实现其余平台可套用同一模型自行组合更省事的选择是直接走 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），仅供参考