Wasp 应用云部署实战指南从wasp build到多平台上线【免费下载链接】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 全栈应用的生产部署流程只要你的托管平台能运行 Node.js 服务器、托管静态文件并提供 PostgreSQL 数据库就可以把wasp build生成的产物部署到任意云环境。读完本文你将掌握生成可部署代码 → 部署 API 服务器 → 部署 Web 客户端 → 部署数据库四步标准流程、生产环境必需的各项环境变量以及 Vercel、Fly.io、Heroku、Railway、Render 等主流平台的部署要点。部署的前置条件云环境必须具备的三项能力Wasp 是一个全家桶式全栈框架一个项目同时产出后端Express Node.js、前端React Vite与数据库访问层Prisma PostgreSQL。因此无论你选择哪家云厂商只要能满足以下三个条件就能部署构建产物运行 Node.js 服务器——承载 Wasp 生成的 API 后端托管静态文件——承载前端构建产物纯 HTML/CSS/JS 静态资源提供 PostgreSQL 数据库——承载应用数据。这也意味着只要你的提供商满足上述条件即便不在官方教程列表内也完全可以手动部署详见 部署到云提供商 一文的手动部署章节。各主流云提供商的官方部署指南一览Wasp 官方为以下 7 个热门平台提供了分步教程覆盖服务器Server客户端Client数据库Database三部分的组合部署方式平台覆盖范围核心技术栈指南位置VercelServer / Client / DatabaseVercel FunctionsExpress preset、Vercel CLI、Supabase 集成web/docs/guides/deployment/cloud-providers/vercel.mdCloudflareClientCloudflare Workers、Wrangler CLIweb/docs/guides/deployment/cloud-providers/cloudflare.mdFly.ioServer / Database另有 CLI 自动化方案fly CLI、Dockerweb/docs/guides/deployment/cloud-providers/flyio.mdHerokuServer / Databaseheroku CLI、Docker 容器web/docs/guides/deployment/cloud-providers/heroku.mdNetlifyClientNetlify CLI、静态托管web/docs/guides/deployment/cloud-providers/netlify.mdRailwayServer / Client / DatabaseRailway CLI、Docker、RAILPACKweb/docs/guides/deployment/cloud-providers/railway.mdRenderServer / Client / DatabaseRender BlueprintIaC、从源码构建web/docs/guides/deployment/cloud-providers/render.md如果你的目标平台不在上表中也无需担心——通用的四步手动部署流程依然适用只是暂时没有官方分步教程。若你有兴趣为某个平台补充教程可以向 Wasp 仓库提交 PR参考web/docs/guides/deployment/cloud-providers/目录下的现有教程格式。手动部署四步走通用流程详解无论目标平台是哪一个部署一个 Wasp 应用本质上都归结为以下四件事生成可部署代码部署 API 服务器后端部署 Web 客户端前端部署并持续运行一个 PostgreSQL 数据库。下面逐一展开。第一步生成可部署代码在项目根目录执行wasp build该命令会为整个应用生成可部署代码输出到.wasp/out/目录。这个目录中包含了服务器端源码、客户端源码、数据库迁移文件以及 Dockerfile 等全部构建产物后续所有部署操作都基于它进行。注意生产环境必须使用 PostgreSQL如果应用还在使用 SQLiteWasp 的默认数据库将无法完成wasp build。在部署到生产环境之前必须先从 SQLite 迁移到 PostgreSQL。第二步部署 API 服务器.wasp/out/目录下自带一个用于构建服务器的 Dockerfile它定义了服务器镜像的完整构建过程。生产环境部署时只需要把这个 Docker 镜像部署到你的托管平台确保所需的环境变量被正确设置通常通过平台的控制台 UI 或 CLI 工具配置。完整的环境变量清单请参考 部署环境变量说明 与 项目环境变量参考。其中服务器侧的关键变量如DATABASE_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、JWT_SECRET、PORT一旦缺失服务器将无法启动。从源码结构看Wasp 的部署工具链位于waspc/data/packages/deploy/src/providers/下也正是围绕构建服务器镜像 注入环境变量 执行数据库迁移这三个动作封装各平台的 CLI 命令例如 Fly.io 与 Railway 的deploy命令都会在发布前调用db-migrate-prod等迁移逻辑。第三步部署 Web 客户端构建客户端需要在项目根目录执行以下命令该片段源自 web/docs/deployment/deployment-methods/_building-the-web-client.mdREACT_APP_API_URLurl_to_wasp_backend npx vite build其中url_to_wasp_backend是你已经部署好的 Wasp 服务器地址。构建完成后客户端产物会输出到.wasp/out/web-app/build/目录其中包括一个位于根目录的200.html文件它充当SPA 路由回退SPA fallback当用户直接访问某个前端路由如/dashboard而服务器上没有对应静态文件时托管平台会返回200.html由前端路由接管渲染。因为构建结果只是一堆静态文件所以你可以把.wasp/out/web-app/build/的内容部署到任何静态托管平台如 Netlify、Cloudflare 等。为了让 SPA 回退生效不同平台需要做对应的配置Netlify在netlify.toml中配置publish ./.wasp/out/web-app/build并添加[[redirects]] from /* to /200.html status 200Vercel在public/vercel.json中配置rewrites: [{ source: /(.*), destination: /200.html }]Cloudflare Workers编写一个worker.js当静态资源未命中时env.ASSETS.fetch回退到/200。200.html回退机制在仓库的 Vite 相关实现中也有迹可循waspc/data/Generator/libs/vite-ssr/src/plugins/common/options.ts等文件负责生成与处理 SPA 回退相关的构建选项与路由逻辑。务必注意如果你在项目中定义了其他客户端环境变量构建客户端时也要一并传给上面的命令否则构建会因缺少必需变量而失败。第四步部署 PostgreSQL 数据库数据库这一环没有特殊要求任何 PostgreSQL 实例都可以只要满足两点即可为服务器提供正确的DATABASE_URL环境变量确保服务器可以访问到该数据库网络连通、白名单放行等。各平台的做法差异在于数据库的供给方式Fly.io 会在fly launch交互中帮你创建并注入DATABASE_URLVercel 通过 Marketplace 集成 Supabase再把POSTGRES_PRISMA_URL复制到DATABASE_URLHeroku 通过heroku addons:create创建并自动设置Render 则在render.yaml中用fromDatabase引用数据库服务自动注入连接串。生产环境环境变量清单在开发时Wasp 支持用.env.client与.env.server两个文件管理环境变量但部署时这两个文件会被忽略你需要通过托管平台自身的机制提供环境变量。两者注入时机也有本质区别客户端环境变量构建时注入客户端环境变量如REACT_APP_API_URL在构建阶段被注入到前端 JS 代码中因此对任何人公开可读绝不能存放密钥。构建命令REACT_APP_API_URLurl_to_wasp_backend REACT_APP_SOME_OTHER_VAR_NAMEsomeothervalue npx vite build其原理是构建时 Wasp/Vite 会把代码中所有import.meta.env.REACT_APP_SOME_VAR_NAME替换为对应值使其固化进静态产物。因此不要尝试在托管平台上给静态站点设置客户端变量——静态文件阶段这些变量已经不起作用了正确姿势是在构建命令里传入。在代码中推荐通过wasp/client暴露的类型化env对象读取而非裸用import.meta.env以获得校验与类型提示。服务器环境变量运行环境提供服务器侧环境变量通过托管平台注入可以安全存放密钥。以下是 Wasp 定义的核心服务器环境变量源自 web/docs/project/env-vars.md变量类型是否必需说明DATABASE_URLString必需应用要连接的 PostgreSQL 数据库 URLWASP_WEB_CLIENT_URLURL必需客户端地址用于邮件中链接、OAuth 回跳等WASP_SERVER_URLURL必需服务器地址用于 OAuth 登录回跳等JWT_SECRETString必需至少 32 字符的随机字符串用于生成安全令牌PORTInteger必需服务器监听端口此外如果启用了邮件发送SMTP / SendGrid / Mailgun / Resend或 OAuth 登录如GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET还需要补充对应提供商的密钥变量使用 PgBoss 执行后台任务时可配置PG_BOSS_NEW_OPTIONSJSON 格式。各平台设置服务器变量的方式Fly.io 用fly secrets set SOME_VAR_NAMEsomevalueHeroku 用heroku config:setVercel 用npx vercel env addRailway 在控制台 Variables 标签页配置Render 则在 Blueprint 的envVars中声明缺失变量用sync: false标记为部署后手动填写。代表平台部署要点速览VercelFunctions 静态站点 SupabaseWasp 服务器在 Vercel 上以 Express preset 封装成单个 Vercel Function。需要在项目根目录创建vercel.json其构建命令与生成的 Dockerfile 逻辑一致安装依赖 →prisma generate→ 打包 → 执行数据库迁移{ $schema: https://openapi.vercel.sh/vercel.json, framework: express, installCommand: npm install, buildCommand: cd .wasp/out/server npm install npx prisma generate --schema../db/schema.prisma npm run bundle DATABASE_URL$POSTGRES_URL_NON_POOLING npm run db-migrate-prod, outputDirectory: .wasp/out/server/bundle }同时需创建.vercelignore排除node_modules、.env*、/migrations迁移文件已由wasp build复制进.wasp/out/db/等目录。由于 Vercel Functions 是无服务器平台有几点限制需要提前确认Jobs 与 WebSockets 不支持、函数默认最长运行 5 分钟、全局状态会被周期性重置、服务端setupFn必须快速完成详见 web/docs/guides/deployment/cloud-providers/vercel.md 与 服务器配置。若应用依赖这些特性建议把服务器部署到其他平台客户端仍可留在 Vercel。Fly.ioDocker fly CLI进入.wasp/out/后执行fly launch --remote-only交互中同意创建 PostgreSQL选 Development 档并暂不部署随后用fly secrets set注入PORT、JWT_SECRET、WASP_WEB_CLIENT_URL、WASP_SERVER_URL再用fly deploy --remote-only --config ../../fly.toml完成部署。注意wasp build会清空.wasp/out/建议把fly.toml复制到项目根目录保存或在重建后用fly config save -a app-name从远端重新生成。Fly.io 同时提供wasp deploy一条命令自动化部署服务器、客户端与数据库详见 web/docs/guides/deployment/cloud-providers/flyio.md。Heroku容器栈 heroku-postgresql创建应用heroku create app-name与数据库heroku addons:create --app app-name heroku-postgresql:essential-0Heroku 会自动设置DATABASE_URL与PORT剩余变量用heroku config:set补齐然后在.wasp/out/中执行heroku stack:set container、heroku container:push web、heroku container:release web完成部署。若使用 PgBoss 任务还需额外设置PG_BOSS_NEW_OPTIONS为{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}因为 Heroku 强制 SSL 且使用自签名证书详见 web/docs/guides/deployment/cloud-providers/heroku.md 与 Jobs。Netlify 与 Cloudflare纯静态客户端托管这两个平台只负责承载客户端。Netlify 在项目根创建netlify.toml后执行npx netlify-cli deploy --prod --filter wasp --no-build--filter wasp用于在 Wasp 生成的 npm workspaces 中选择正确的包--no-build表示复用本地已构建产物Cloudflare 则创建wrangler.toml与worker.js后执行npx wrangler deploy。两者都支持通过 GitHub Actions 在推送main分支时自动部署示例工作流分别位于 netlify.md 与 cloudflare.md。部署完成后务必把客户端域名设置为服务器侧的WASP_WEB_CLIENT_URL。RailwayDocker 服务器 静态客户端Railway 项目内建 PostgreSQL 服务并创建server与client两个空服务server服务直接通过.wasp/out/目录railway linkrailway up --ci部署Railway 会自动识别其中的 Dockerfileclient服务则需要在.wasp/out/web-app/build/内放置railway.json指定RAILPACK构建器和自定义Caddyfile实现安全响应头、gzip/zstd 压缩与try_files ... /200.html的 SPA 回退后同样执行railway up --ci。该 Caddyfile 与railway.json与部署工具链源码waspc/data/packages/deploy/src/providers/railway/commands/deploy/client.ts中生成的配置保持一致详见 railway.md。RenderBlueprint 基础设施即代码Render 是唯一从源码构建的平台把仓库推送到 Git 后Render 依据根目录的render.yamlBlueprint 自动创建数据库、服务器与客户端三个资源。服务器构建命令会全局安装 Wasp CLI 并执行wasp install wasp build npm run bundle客户端则以静态站点发布.wasp/out/web-app/build并通过routes重写回退到/200.html。首次部署会因WASP_SERVER_URL、WASP_WEB_CLIENT_URL、REACT_APP_API_URL缺失而失败待拿到两个服务域名后补填并触发重建即可。注意 Render 免费版 PostgreSQL 数据库 30 天后过期生产环境建议使用 Starter 计划或外部数据库详见 render.md。部署到未列出的平台如果你的提供商不在官方指南列表内通用流程完全适用wasp build生成代码 → 用.wasp/out/中的 Dockerfile 部署服务器 → 用REACT_APP_API_URL... npx vite build构建客户端并托管.wasp/out/web-app/build/静态文件 → 提供可达的 PostgreSQL 并注入DATABASE_URL→ 按上文清单设置其余生产环境变量。若你希望托管平台内置自动部署能力也可以把 Wasp 的构建命令编排进该平台的 CI/CD 流程Wasp CLI 的相关命令详见 CLI 文档。小结部署 Wasp 应用的通用公式是wasp build Node.js 服务器 静态文件托管 PostgreSQL四要素缺一不可客户端变量REACT_APP_*在构建时注入、公开可见服务端变量DATABASE_URL、JWT_SECRET、WASP_SERVER_URL等在运行时注入、可存密钥SPA 路由回退200.html是客户端部署的关键配置点各平台通过 rewrite/redirect 规则或自定义 Worker 实现对 Vercel 这类无服务器平台部署前务必确认应用不依赖 Jobs、WebSockets 与长驻全局状态优先考虑各平台的官方分步指南见 web/docs/guides/deployment/cloud-providers/或使用wasp deploy一键部署方案获得自动化体验。【免费下载链接】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），仅供参考