Wasp v0.13 手动部署实战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 v0.13 版本文档《Deploying Manually》为蓝本系统讲解 Wasp 应用的完整手动部署流程从wasp build生成可部署产物到 API 服务器、Web 客户端与 PostgreSQL 数据库三大组件的环境变量契约与逐平台部署实操。读完本文你将能够独立判断任意云平台是否满足 Wasp 构建产物的部署条件并照抄本文命令将应用完整上线同时理解每个环境变量在 waspc 源码中的真实消费位置。一、部署 Wasp 应用的四大步骤总览Wasp 应用的部署本质上由四个步骤构成生成可部署代码wasp build部署 API 服务器后端基于 Docker 镜像部署 Web 客户端前端纯静态资源;部署 PostgreSQL 数据库并保证它持续运行。这套分解方式决定了 Wasp 对托管平台的要求极低只要平台能跑一个 Docker 容器、能托管静态文件、能提供一个可达的 PostgreSQL 实例就可以承载一个 Wasp 应用——这也是手动部署区别于 CLI 一键部署的核心价值。文档原文还特别指出如果你的目标平台不在官方逐平台指南Fly.io / Netlify / Railway / Heroku列表中只要满足上述条件依然可以部署只是缺少现成的 step-by-step 教程而已。二、第一步用wasp build生成可部署代码在项目根目录运行wasp build该命令会把整个应用的可部署代码生成到.wasp/build/目录后续所有平台操作都基于这个目录展开。从源码结构看build是 waspcWasp 编译器的 Haskell 实现中一个显式的构建模式。BuildType.hs 中定义了Project is being compiled for production/deployment (e.g. wasp build)这一构建类型与开发模式wasp start区分开DbGenerator.hs 中也专门处理了 build 场景下没有真实数据库可连接的边界逻辑。wasp build的端到端行为由 e2e 测试覆盖例如 WaspBuildTest.hs 与快照测试 WaspBuildSnapshotTest.hs。重要限制生产环境必须用 PostgreSQL如果你正在使用默认的 SQLite 数据库wasp build将无法为生产环境构建应用。部署到生产环境前必须先切换到 PostgreSQL参见该版本>clientUrlEnvVarName :: String clientUrlEnvVarName WASP_WEB_CLIENT_URL serverUrlEnvVarName :: String serverUrlEnvVarName WASP_SERVER_URL serverPortEnvVarName :: String serverPortEnvVarName -- Not prefixed with WASP_ because many deployment platforms use this env. PORT注释也解释了为什么PORT不加WASP_前缀——因为许多部署平台原生使用这个变量名。四、第三步部署 Web 客户端前端构建前端的操作如下cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你已经部署的Wasp 服务器 URL。构建完成后前端产物位于web-app目录下的build/目录。由于 Wasp 前端本质上就是一堆静态文件它可以部署到任意静态托管平台Netlify、Vercel、对象存储 CDN 等。REACT_APP_API_URL会在构建期内联进客户端代码决定浏览器端发起 RPC 请求的 API 基地址——这也是为什么客户端构建必须在服务器部署或至少确定了域名之后进行。五、第四步部署数据库任何 PostgreSQL 数据库都可以条件只有两条通过DATABASE_URL环境变量把连接信息提供给服务器保证数据库从服务器所在网络可达。六、Fly.io 实操服务器 数据库如果你的目标是 Fly.io也可以直接用 Wasp CLI 自动完成下面的全部工作部署服务器、部署客户端、建立数据库并支持单命令重新部署参见 Wasp CLI 文档。准备工作一个 Fly.io 账号 flyctlCLI大多数系统上fly是flyctl的软链可互换使用。本文默认使用远程构建remote builder以获得更好的可复现性。先确认登录状态flyctl auth whoami # 检查是否已登录 flyctl auth login # 未登录时执行6.1 创建 Fly.io 应用每个 Wasp 应用只需做一次先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 dashboard 中形如接着把fly.toml拷回 Wasp 项目根目录妥善保存后面重新部署要用cp fly.toml ../../再补齐剩余环境变量flyctl secrets set存储在平台侧不写入本地文件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如果你使用外部认证方式Google/GitHub 等此处同样需要追加对应环境变量。若客户端 URL 尚未确定可以先部署客户端再回来补设WASP_WEB_CLIENT_URL。用flyctl secrets list可验证 secrets 已添加出于安全列表里显示的是哈希值。6.2 部署到 Fly.io仍在.wasp/build/目录下执行flyctl deploy --remote-only --config ../../fly.toml这会构建并部署后端到https://app-name.fly.dev。若客户端尚未部署部署后执行flyctl secrets set WASP_WEB_CLIENT_URL客户端实际URL补上建议用 Netlify 托管客户端任何静态托管均可。常用运维命令flyctl logs # 查看日志 flyctl secrets list # 查看环境变量 flyctl ssh console # 进入容器 shell6.3 重新构建后如何再部署fly.toml 保命三策wasp build会删除整个.wasp/build/目录连同其中可能存在的fly.toml。在官方流程改进之前有三种选择版本化保存把fly.toml拷进 Wasp 项目根目录推荐之后在flyctl deploy --config path中引用它如上文示例手动备份还原wasp build前备份fly.toml构建后再拷回.wasp/build/。文件位于该目录时flyctl deploy无需--config参数从远端拉回执行flyctl config save -a app-name从 Fly.io 远端状态重新生成fly.toml。七、Netlify 实操客户端前置条件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。关键收尾务必把这个 Netlify URL 设置为服务器托管环境Fly.io / Heroku / Railway 等中的WASP_WEB_CLIENT_URL环境变量——这是 CORS 生效的前提。八、Railway 实操服务器 客户端 数据库一站式Railway 可以同时承载数据库、服务器与客户端实现全家桶部署。前置条件wasp build完成、Railway 账号用 GitHub 账号注册可获免费额度、Railway CLI 安装并执行railway login会打开浏览器认证。8.1 创建项目在 Railway dashboard 点New Project下拉菜单选择Provision PostgreSQL初始化完成后右键点击右上角New按钮选择Empty Service初始化后点进该服务进入Settings General把名字改成server再创建一个空服务命名为client。8.2 配置域名server与client两个服务都需要固定域名供环境变量引用进入各自Settings标签页点击Generate Domain把生成的两个域名抄下来备用。8.3 部署服务器cd .wasp/build railway link然后在 Railway dashboard 的server服务Settings Variables中配置点击Variable reference选择DATABASE_URL平台会自动填入 PostgreSQL 的正确值新增WASP_WEB_CLIENT_URL填client服务的域名新增WASP_SERVER_URL填server服务的域名新增JWT_SECRET至少 32 字符的随机字符串。使用外部认证方式时同样追加其专属变量。推送部署railway up在Select Service提示时选择server。Railway 会自动找到 Dockerfile 并部署。8.4 部署客户端静态托管进入前端目录cd web-app # 即 .wasp/build/web-app用server域名构建生产包npm install REACT_APP_API_URLurl_to_wasp_backend npm run build将该目录也 link 到项目railway link配置 Railway 静态托管把web-app内的build文件夹拷贝为dist并创建两个文件cp -r build distDockerfile基于 gostatic-fallback index.html实现 SPA 前端路由回退FROM 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在client服务的Variables中把PORT设为8043gostatic 默认监听端口。部署客户端railway upSelect Service时选择client。至此 PostgreSQL、Server、Client 三个服务应全部出现在 Railway dashboard 中。8.5 更新与重新部署每次迭代重复三步wasp build重建 → 在.wasp/build中railway up服务器→ 在.wasp/build/web-app中重跑客户端全套步骤。九、Heroku 实操服务器 数据库Heroku 自 2022 年 11 月 28 日起取消了免费套餐其最便宜的数据库实例heroku-postgresql:mini每月 5 美元。因此官方文档建议第一个 Wasp 应用优先选择 Fly.io 这类仍提供免费额度的平台。前置条件Heroku 账号、herokuCLI 与dockerCLI。用heroku whoami/heroku login检查与登录。9.1 创建应用与数据库每个 Wasp 应用只需一次heroku create app-name heroku addons:create --app app-name heroku-postgresql:mini创建 PostgreSQL 附加组件时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。9.2 推送镜像并部署wasp build后进入构建目录假设当前在项目根cd .wasp/build heroku container:login heroku container:push --app app-name web这一步只是构建并推送镜像应用尚未真正部署首次推送因没有缓存层会比较慢。Apple Silicon 用户注意heroku container:push在 Apple Silicon 上无法构建非 Arm 镜像需改用 docker buildx 手动完成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跟踪日志。9.3 附加说明pg-boss 与 Heroku如果应用使用了基于pg-boss执行器的Jobs后台任务功能并部署到 Heroku需要额外设置环境变量PG_BOSS_NEW_OPTIONS{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}原因pg-boss 依赖的pg扩展默认不走 SSL而 Heroku 强制 SSL 连接且使用自签名证书需要显式放开rejectUnauthorized并指定连接串。十、Koyeb整站部署官方还收录了 Koyeb 团队针对 Wasp v0.13 撰写的整站部署教程服务器 客户端 数据库可作为第五种平台参考具体步骤以该教程为准。十一、小结一份可对照的部署检查清单组件产物部署载体关键环境变量可部署代码wasp build→.wasp/build/本地目录—API 服务器.wasp/build/中的 Docker 镜像Fly.io / Railway / Heroku 等 Docker 平台DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET、PORT默认 3001Web 客户端.wasp/build/web-app/build/静态文件Netlify 等任意静态托管构建期REACT_APP_API_URL数据库任意 PostgreSQL 实例Fly.io / Railway / Heroku 托管 PG 或自建通过DATABASE_URL暴露给服务器理解这张表就理解了 Wasp 手动部署的全部wasp build产出一个自包含的 Docker 后端 一个可独立构建的静态前端 一份明确的五变量环境契约任何平台只要满足这三点即可承载。若目标平台是 Fly.io建议先熟悉本文手动流程再切换 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），仅供参考 
长河君 · 2026/9/14 11:54:58 · 阅读 1.2k Wasp v0.13 手动部署实战：wasp build 构建产物与环境变量体系，以及 Fly.io / Netlify / Railway / Heroku 四平台落地指南
Wasp v0.13 手动部署实战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 v0.13 版本文档《Deploying Manually》为蓝本系统讲解 Wasp 应用的完整手动部署流程从wasp build生成可部署产物到 API 服务器、Web 客户端与 PostgreSQL 数据库三大组件的环境变量契约与逐平台部署实操。读完本文你将能够独立判断任意云平台是否满足 Wasp 构建产物的部署条件并照抄本文命令将应用完整上线同时理解每个环境变量在 waspc 源码中的真实消费位置。一、部署 Wasp 应用的四大步骤总览Wasp 应用的部署本质上由四个步骤构成生成可部署代码wasp build部署 API 服务器后端基于 Docker 镜像部署 Web 客户端前端纯静态资源;部署 PostgreSQL 数据库并保证它持续运行。这套分解方式决定了 Wasp 对托管平台的要求极低只要平台能跑一个 Docker 容器、能托管静态文件、能提供一个可达的 PostgreSQL 实例就可以承载一个 Wasp 应用——这也是手动部署区别于 CLI 一键部署的核心价值。文档原文还特别指出如果你的目标平台不在官方逐平台指南Fly.io / Netlify / Railway / Heroku列表中只要满足上述条件依然可以部署只是缺少现成的 step-by-step 教程而已。二、第一步用wasp build生成可部署代码在项目根目录运行wasp build该命令会把整个应用的可部署代码生成到.wasp/build/目录后续所有平台操作都基于这个目录展开。从源码结构看build是 waspcWasp 编译器的 Haskell 实现中一个显式的构建模式。BuildType.hs 中定义了Project is being compiled for production/deployment (e.g. wasp build)这一构建类型与开发模式wasp start区分开DbGenerator.hs 中也专门处理了 build 场景下没有真实数据库可连接的边界逻辑。wasp build的端到端行为由 e2e 测试覆盖例如 WaspBuildTest.hs 与快照测试 WaspBuildSnapshotTest.hs。重要限制生产环境必须用 PostgreSQL如果你正在使用默认的 SQLite 数据库wasp build将无法为生产环境构建应用。部署到生产环境前必须先切换到 PostgreSQL参见该版本>clientUrlEnvVarName :: String clientUrlEnvVarName WASP_WEB_CLIENT_URL serverUrlEnvVarName :: String serverUrlEnvVarName WASP_SERVER_URL serverPortEnvVarName :: String serverPortEnvVarName -- Not prefixed with WASP_ because many deployment platforms use this env. PORT注释也解释了为什么PORT不加WASP_前缀——因为许多部署平台原生使用这个变量名。四、第三步部署 Web 客户端前端构建前端的操作如下cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你已经部署的Wasp 服务器 URL。构建完成后前端产物位于web-app目录下的build/目录。由于 Wasp 前端本质上就是一堆静态文件它可以部署到任意静态托管平台Netlify、Vercel、对象存储 CDN 等。REACT_APP_API_URL会在构建期内联进客户端代码决定浏览器端发起 RPC 请求的 API 基地址——这也是为什么客户端构建必须在服务器部署或至少确定了域名之后进行。五、第四步部署数据库任何 PostgreSQL 数据库都可以条件只有两条通过DATABASE_URL环境变量把连接信息提供给服务器保证数据库从服务器所在网络可达。六、Fly.io 实操服务器 数据库如果你的目标是 Fly.io也可以直接用 Wasp CLI 自动完成下面的全部工作部署服务器、部署客户端、建立数据库并支持单命令重新部署参见 Wasp CLI 文档。准备工作一个 Fly.io 账号 flyctlCLI大多数系统上fly是flyctl的软链可互换使用。本文默认使用远程构建remote builder以获得更好的可复现性。先确认登录状态flyctl auth whoami # 检查是否已登录 flyctl auth login # 未登录时执行6.1 创建 Fly.io 应用每个 Wasp 应用只需做一次先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 dashboard 中形如接着把fly.toml拷回 Wasp 项目根目录妥善保存后面重新部署要用cp fly.toml ../../再补齐剩余环境变量flyctl secrets set存储在平台侧不写入本地文件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如果你使用外部认证方式Google/GitHub 等此处同样需要追加对应环境变量。若客户端 URL 尚未确定可以先部署客户端再回来补设WASP_WEB_CLIENT_URL。用flyctl secrets list可验证 secrets 已添加出于安全列表里显示的是哈希值。6.2 部署到 Fly.io仍在.wasp/build/目录下执行flyctl deploy --remote-only --config ../../fly.toml这会构建并部署后端到https://app-name.fly.dev。若客户端尚未部署部署后执行flyctl secrets set WASP_WEB_CLIENT_URL客户端实际URL补上建议用 Netlify 托管客户端任何静态托管均可。常用运维命令flyctl logs # 查看日志 flyctl secrets list # 查看环境变量 flyctl ssh console # 进入容器 shell6.3 重新构建后如何再部署fly.toml 保命三策wasp build会删除整个.wasp/build/目录连同其中可能存在的fly.toml。在官方流程改进之前有三种选择版本化保存把fly.toml拷进 Wasp 项目根目录推荐之后在flyctl deploy --config path中引用它如上文示例手动备份还原wasp build前备份fly.toml构建后再拷回.wasp/build/。文件位于该目录时flyctl deploy无需--config参数从远端拉回执行flyctl config save -a app-name从 Fly.io 远端状态重新生成fly.toml。七、Netlify 实操客户端前置条件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。关键收尾务必把这个 Netlify URL 设置为服务器托管环境Fly.io / Heroku / Railway 等中的WASP_WEB_CLIENT_URL环境变量——这是 CORS 生效的前提。八、Railway 实操服务器 客户端 数据库一站式Railway 可以同时承载数据库、服务器与客户端实现全家桶部署。前置条件wasp build完成、Railway 账号用 GitHub 账号注册可获免费额度、Railway CLI 安装并执行railway login会打开浏览器认证。8.1 创建项目在 Railway dashboard 点New Project下拉菜单选择Provision PostgreSQL初始化完成后右键点击右上角New按钮选择Empty Service初始化后点进该服务进入Settings General把名字改成server再创建一个空服务命名为client。8.2 配置域名server与client两个服务都需要固定域名供环境变量引用进入各自Settings标签页点击Generate Domain把生成的两个域名抄下来备用。8.3 部署服务器cd .wasp/build railway link然后在 Railway dashboard 的server服务Settings Variables中配置点击Variable reference选择DATABASE_URL平台会自动填入 PostgreSQL 的正确值新增WASP_WEB_CLIENT_URL填client服务的域名新增WASP_SERVER_URL填server服务的域名新增JWT_SECRET至少 32 字符的随机字符串。使用外部认证方式时同样追加其专属变量。推送部署railway up在Select Service提示时选择server。Railway 会自动找到 Dockerfile 并部署。8.4 部署客户端静态托管进入前端目录cd web-app # 即 .wasp/build/web-app用server域名构建生产包npm install REACT_APP_API_URLurl_to_wasp_backend npm run build将该目录也 link 到项目railway link配置 Railway 静态托管把web-app内的build文件夹拷贝为dist并创建两个文件cp -r build distDockerfile基于 gostatic-fallback index.html实现 SPA 前端路由回退FROM 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在client服务的Variables中把PORT设为8043gostatic 默认监听端口。部署客户端railway upSelect Service时选择client。至此 PostgreSQL、Server、Client 三个服务应全部出现在 Railway dashboard 中。8.5 更新与重新部署每次迭代重复三步wasp build重建 → 在.wasp/build中railway up服务器→ 在.wasp/build/web-app中重跑客户端全套步骤。九、Heroku 实操服务器 数据库Heroku 自 2022 年 11 月 28 日起取消了免费套餐其最便宜的数据库实例heroku-postgresql:mini每月 5 美元。因此官方文档建议第一个 Wasp 应用优先选择 Fly.io 这类仍提供免费额度的平台。前置条件Heroku 账号、herokuCLI 与dockerCLI。用heroku whoami/heroku login检查与登录。9.1 创建应用与数据库每个 Wasp 应用只需一次heroku create app-name heroku addons:create --app app-name heroku-postgresql:mini创建 PostgreSQL 附加组件时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。9.2 推送镜像并部署wasp build后进入构建目录假设当前在项目根cd .wasp/build heroku container:login heroku container:push --app app-name web这一步只是构建并推送镜像应用尚未真正部署首次推送因没有缓存层会比较慢。Apple Silicon 用户注意heroku container:push在 Apple Silicon 上无法构建非 Arm 镜像需改用 docker buildx 手动完成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跟踪日志。9.3 附加说明pg-boss 与 Heroku如果应用使用了基于pg-boss执行器的Jobs后台任务功能并部署到 Heroku需要额外设置环境变量PG_BOSS_NEW_OPTIONS{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}原因pg-boss 依赖的pg扩展默认不走 SSL而 Heroku 强制 SSL 连接且使用自签名证书需要显式放开rejectUnauthorized并指定连接串。十、Koyeb整站部署官方还收录了 Koyeb 团队针对 Wasp v0.13 撰写的整站部署教程服务器 客户端 数据库可作为第五种平台参考具体步骤以该教程为准。十一、小结一份可对照的部署检查清单组件产物部署载体关键环境变量可部署代码wasp build→.wasp/build/本地目录—API 服务器.wasp/build/中的 Docker 镜像Fly.io / Railway / Heroku 等 Docker 平台DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET、PORT默认 3001Web 客户端.wasp/build/web-app/build/静态文件Netlify 等任意静态托管构建期REACT_APP_API_URL数据库任意 PostgreSQL 实例Fly.io / Railway / Heroku 托管 PG 或自建通过DATABASE_URL暴露给服务器理解这张表就理解了 Wasp 手动部署的全部wasp build产出一个自包含的 Docker 后端 一个可独立构建的静态前端 一份明确的五变量环境契约任何平台只要满足这三点即可承载。若目标平台是 Fly.io建议先熟悉本文手动流程再切换 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），仅供参考