Wasp 单命令自动化部署Wasp Deploy完整指南从wasp deploy到 Fly.io 与 Railway 的生产落地【免费下载链接】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 提供了一键式自动化部署方案Wasp Deploy通过wasp deploy provider launch app-name一条命令即可在云平台上完成服务注册、数据库创建、应用构建与发布的全流程。本文以 Wasp v0.18 官方文档为骨架结合仓库内 Haskell CLI 与wasp/deploy包源码深入讲解命令执行链、自动注入的环境变量、Fly.io 与 Railway 两大支持平台的使用细节帮助你快速把 Wasp 全栈应用部署到生产环境。什么是 Wasp Deploy一条命令完成全栈部署Wasp 应用是一个由三部分组成的全栈应用一个 Node.js 服务端、一个静态客户端和一个 PostgreSQL 数据库参见 部署总览。如果手动部署你需要分别在云平台上创建服务、配置数据库、注入环境变量、构建镜像并发布——步骤繁多且容易出错。Wasp Deploy 正是为了解决这一问题而设计的Wasp CLI 可以用一条命令部署你的全栈应用命令会自动接管原本需要人工完成的部署流程也是官方推荐的 Wasp 应用部署方式。它看起来像这样wasp deploy provider launch my-wasp-app执行这条命令后Wasp CLI 会替你完成三件事在目标云平台上创建并配置所有必要的服务客户端服务、服务端服务、数据库构建你的 Wasp 应用生成可部署代码、构建 Docker 镜像把构建产物部署到云平台。从 CLI 帮助文档也可以看到wasp deploy的定位正是让应用轻松托管到 Web 上参见 CLI 参考。支持的云平台目前 Wasp Deploy 支持以下两家云平台点击对应平台可查看详细部署步骤Fly.io 部署指南面向全球运行容器化应用与微服务的平台Railway 部署指南内置数据库与服务的云端开发平台。两个平台的入口在 WaspDeployProvidersGrid.tsx 中统一定义后续若新增平台只需在该组件中追加条目即可。底层原理wasp deploy是如何被执行的要理解wasp deploy的价值先看看它的底层实现。Wasp CLI 的主体是一个 Haskell 程序位于 waspc 目录但部署逻辑本身由 npm 包wasp/deploy源码在 waspc/data/packages/deploy实现。在 Wasp.Project.Deployment 模块 中deploy函数负责把部署命令委托给这个 npm 包deploy waspExe waspDir cmdArgs do let deployScriptArgs concat [cmdArgs, [--wasp-exe, waspExe, --wasp-project-dir, toFilePath waspDir]] cp - getPackageProcessOptions DeployPackage deployScriptArgs ...这段代码揭示了两点关键设计--wasp-exe与--wasp-project-dir是隐藏的必填参数Haskell CLI 会把 wasp 可执行文件路径与当前项目目录透传给部署包部署包据此校验项目合法性、调用wasp build等子命令标准输入/输出/错误均继承自 waspc 进程部署过程中的所有提示、进度、错误信息会直接呈现在终端中并且delegate_ctlc True让 CtrlC 能被正确传递给子进程——这就是文档中反复提醒命令运行期间不要 CtrlC 或退出终端的原因。因此wasp deploy fly ...或wasp deploy railway ...本质上是一条从 Haskell CLI 到 TypeScript 部署包的命令转发 项目上下文注入链路保证部署包始终与正确的 Wasp 项目绑定。使用 Fly.io 部署 Wasp 应用Fly.io 是一个在全球服务器上运行容器化应用和微服务的平台用最少的前期配置即可部署和管理应用。前置条件注册一个 Fly.io 账号Fly 要求先添加付款方式才能部署超过两个 Fly 应用——部署 Wasp 应用需要三个 Fly 应用客户端、服务端、数据库所以必须提前完成在本地机器上安装flyCLI。单命令启动应用wasp deploy fly launch my-wasp-app mia其中my-wasp-app是应用基础名mia是部署区域mia是佛罗里达州迈阿密区域的简称。命令运行期间请勿 CtrlC 或退出终端。有两点必须注意应用名必须全局唯一你的应用名如my-wasp-app在 Fly 全网必须唯一否则部署会失败多组织账号需指定组织如果你的 Fly 账号属于多个组织需要通过--org org-slug参数指定在哪个组织下执行命令可用fly orgs list查看组织名。launch命令会以基础名创建三个独立的 Fly 应用它们会出现在你的 Fly 控制台中my-wasp-app-clientmy-wasp-app-servermy-wasp-app-db同时Wasp 会在项目根目录生成两个新文件fly-server.toml和fly-client.toml。你应该把它们纳入版本控制这样以后就能用单条命令再次部署。仓库中的 examples/ask-the-documents/fly-server.toml 就是真实项目生成的示例app ask-the-documents-server primary_region cdg [build] [http_service] internal_port 8080 force_https true auto_stop_machines stop auto_start_machines true min_machines_running 1 processes [app] [[vm]] memory 1gb cpu_kind shared cpus 1为应用配置自定义域名自定义域名分三步完成为 Fly 客户端应用添加域名wasp deploy fly cmd --context client certs create mycoolapp.com注意把mycoolapp.com替换成你自己的域名。该命令会输出添加 DNS 记录的指引类似You can direct traffic to mycoolapp.com by: 1: Adding an A record to your DNS service which reads A 66.241.1XX.154 You can validate your ownership of mycoolapp.com by: 2: Adding an AAAA record to your DNS service which reads: AAAA 2a09:82XX:1::1:ff40为域名添加 DNS 记录具体操作取决于你的域名服务商但本质上是按照上一步输出的值为添加 A 记录和 AAAA 记录把域名设置为服务端应用的WASP_WEB_CLIENT_URL环境变量wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URLhttps://mycoolapp.com这一步是为了让 CORS 配置保持最新。完成后你的应用就可以通过https://mycoolapp.com访问了。添加www子域名如果还想通过https://www.mycoolapp.com访问可以为www子域名生成证书wasp deploy fly cmd --context client certs create www.mycoolapp.com随后为域名添加一条 CNAME 记录把www指向根域名TypeNameValueTTLCNAMEwwwmycoolapp.com3600CNAMECanonical name记录把www子域名设置为根域名的别名。之后你的应用在根域名和www子域名下都能访问。⚠️CORS 配置提醒同时使用www和非www域名时需要为服务端应用提供自定义 CORS 配置允许来自两个域名的请求。Fly.io 部署 API 参考launch命令launch是一个便捷命令按顺序依次执行setup、create-db和deploywasp deploy fly launch app-name region参数说明app-name必填你的应用名region必填部署区域可用fly platform regions查看可用区域列表。运行wasp deploy fly launch等价于依次运行wasp deploy fly setup app-name region wasp deploy fly create-db region wasp deploy fly deploy从部署包源码 launch.ts 可以看到launch会先检查项目中是否已存在 Fly 的 TOML 文件——如果已存在会直接报错提示launch 命令只应用于全新的 Fly 项目否则依次调用setup、createDb、deploy。这也解释了为什么launch只应在首次部署时使用。setup命令setup命令在 Fly 上注册你的客户端与服务端应用并配置所需的环境变量。它只在首次创建应用时需要运行一次不会触发任何部署wasp deploy fly setup app-name region运行setup后Wasp 会在项目根目录创建fly-server.toml和fly-client.toml两个文件建议纳入版本控制。你可以编辑这两个 TOML 文件进一步自定义 Fly 部署配置后续deploy时会使用它们。如果维护多个应用可用--fly-toml-dir abs-path指向不同目录如dev或staging。⚠️只执行一次setup每个应用只应运行一次重复运行会在 Fly 上创建多余的应用。create-db命令create-db命令为你的应用创建数据库wasp deploy fly create-db region参数说明region必填部署区域。⚠️只执行一次create-db每个应用只应运行一次重复运行会创建多个数据库而你的应用只需要一个。deploy命令deploy命令把构建好的客户端和服务端推送到线上wasp deploy fly deploy每次要更新已部署的应用时都运行这个命令即可。如果你在应用中添加了客户端环境变量需要在运行部署命令前把它们传入终端会话例如REACT_APP_ANOTHER_VARsomevalue wasp deploy fly deploy每次重新部署都必须指定客户端环境变量以确保它们被包含进构建过程。cmd命令如果想运行任意的 Fly 命令例如查看服务端应用的密钥列表wasp deploy fly cmd secrets list --context serverFly.io 环境变量管理服务端密钥Server Secrets如果你的应用需要其他服务端环境变量如社交登录密钥有两种设置方式在launch或setup命令中通过--server-secret选项一次性设置wasp deploy fly launch my-wasp-app mia --server-secret GOOGLE_CLIENT_ID... --server-secret GOOGLE_CLIENT_SECRET...应用部署完成后使用secrets set命令补充设置wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID... GOOGLE_CLIENT_SECRET... --contextserver客户端环境变量如果你在应用中添加了客户端环境变量在运行部署命令前把它们传入终端会话REACT_APP_ANOTHER_VARsomevalue wasp deploy fly launch my-wasp-app mia或REACT_APP_ANOTHER_VARsomevalue wasp deploy fly deploy注意每次部署都要带上这些变量不只是首次。一个防止遗忘的办法是在package.json中创建deploy脚本{ scripts: { deploy: REACT_APP_ANOTHER_VARsomevalue wasp deploy fly deploy } }之后运行npm run deploy即可完成部署。其他 Fly.io 选项多个 Fly 组织通过--org选项指定例如wasp deploy fly launch my-wasp-app mia --org hive本地构建Fly 同时支持本地构建和远程构建 Docker 容器出于简单性和可复现性CLI 默认使用 Fly 的远程构建器。如需本地构建在launch或deploy命令后追加--build-locally选项。命令参数源码速览fly/index.ts 中集中定义了 Fly 子命令的参数模型从中可以确认文档未展开的默认值数据库选项--db-vm-size默认shared-cpu-1x、--db-vm-memory、--db-vm-cpus、--db-vm-cpu-kind、--db-initial-cluster-size默认1、--db-volume-size默认1GB、--db-image默认flyio/postgres-flex:18密钥选项--server-secret与--client-secret格式均为FOOBAR可重复传入--custom-server-url指定客户端连接的服务器 URL部署跳过选项deploy支持--skip-client与--skip-server所有 Fly 子命令在执行前都会先做合法性校验验证 Wasp 项目目录存在、验证区域代码有效并确保flyctl可用。使用 Railway 部署 Wasp 应用Railway 是一个云端开发平台内置数据库与服务支持界面直观且自动化处理基础设施。前置条件注册一个 Railway 账号在本地机器上安装railwayCLI。单命令启动应用wasp deploy railway launch my-wasp-app命令运行期间请勿 CtrlC 或退出终端。有两点必须注意项目名必须唯一你的项目名如my-wasp-app在你自己的全部 Railway 项目中必须唯一否则部署会失败这是当前 Wasp CLI 与 Railway 集成的已知限制对应 wasp-lang/wasp issue #2926多组织账号会被提示选择组织如果你是多个 Railway 组织的成员CLI 会提示你选择要在哪个组织下部署应用。项目名被用作客户端和服务端服务名的前缀my-wasp-app-clientmy-wasp-app-server由于 Railway CLI 不允许自定义数据库服务名数据库服务始终命名为Postgres。为应用配置自定义域名自定义域名分三步完成把域名添加到 Railway 客户端服务进入 Railway 控制台选择你的项目如my-wasp-app点击客户端服务如my-wasp-app-client进入Settings选项卡点击Custom Domain输入你的域名如mycoolapp.com和端口8080点击Add Domain。更新域名的 DNS 记录在目标域名或子域名处添加一条 CNAME 记录指向上一步给出的地址。这一步取决于你的域名服务商。更新WASP_WEB_CLIENT_URL以避免 CORS 错误把新的客户端 URL如https://mycoolapp.com设置为服务端服务的WASP_WEB_CLIENT_URL环境变量进入 Railway 控制台选择项目点击服务端服务如my-wasp-app-server进入Variables选项卡更新WASP_WEB_CLIENT_URL变量。完成后你的应用就可以通过https://mycoolapp.com访问了。Railway 部署 API 参考launch命令launch是便捷命令按顺序执行setup和deploywasp deploy railway launch project-name参数说明project-name必填你的项目名。运行wasp deploy railway launch等价于依次运行wasp deploy railway setup project-name wasp deploy railway deploy project-name显式指定 Railway 项目 ID默认情况下Wasp CLI 会尝试创建名为project-name的新 Railway 项目。如果想使用现有项目通过--existing-project-id传入项目 IDwasp deploy railway launch project-name --existing-project-id railway-project-id显式指定 Railway Workspace默认情况下Wasp CLI 会提示你为项目选择一个 Railway workspace。想跳过提示、直接指定 workspace 的 ID 或名称使用--workspace选项wasp deploy railway launch project-name --workspace railway-workspace-id-or-name环境变量服务端如果应用需要其他环境变量如社交登录密钥用--server-secret选项设置wasp deploy railway launch my-wasp-app --server-secret GOOGLE_CLIENT_ID... --server-secret GOOGLE_CLIENT_SECRET...客户端如果添加了客户端环境变量在运行launch命令前传入终端会话REACT_APP_ANOTHER_VARsomevalue wasp deploy railway launch my-wasp-appdeploy命令deploy命令把客户端和服务端应用部署到 Railwaywasp deploy railway deploy project-name参数说明project-name必填你的项目名。每次要更新已部署的应用时都运行该命令。运行deploy时Wasp CLI 会使用与 Wasp 项目目录关联的 Railway 项目如果尚未关联命令会失败并要求你先运行setup。在 CI 中部署时可以通过--existing-project-id告诉 Wasp CLI 要使用的 Railway 项目 IDwasp deploy railway deploy project-name --existing-project-id railway-project-id其他可用选项--skip-client不部署 Web 客户端--skip-server不部署服务端。客户端环境变量同样需要在每次部署时传入终端会话REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy project-namesetup命令setup命令在 Railway 上创建你的客户端、服务端和数据库服务并配置环境变量但不会部署客户端或服务端服务wasp deploy railway setup project-name参数说明project-name你的项目名。项目名被用作服务名的前缀project-name-clientproject-name-serverRailway 还会创建一个名为Postgres的 PostgreSQL 数据库服务。setup同样支持--existing-project-id与--workspace选项语义与launch相同。⚠️只执行一次setup每个应用只应运行一次。如果服务已存在Wasp CLI 会跳过创建。Railway 环境变量管理服务端密钥有两种设置方式在launch或setup命令中用--server-secret选项设置应用部署完成后进入 Railway 控制台在服务端服务的Variables选项卡中设置。客户端环境变量在运行部署命令前传入终端会话例如REACT_APP_ANOTHER_VARsomevalue wasp deploy railway launch my-wasp-app或REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy每次部署都要带上这些变量不只是首次。同样可以用package.json中的deploy脚本固化{ scripts: { deploy: REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy } }然后运行npm run deploy完成部署。Railway 命令参数源码速览railway/index.ts 中定义了 Railway 子命令的参数模型几点值得注意的默认值数据库镜像默认值--db-image默认ghcr.io/railwayapp-templates/postgres-ssl:18--db-volume-mount-path默认/var/lib/postgresql/data——两个默认值都注释说明与 Wasp 开发数据库的 Postgres 主版本保持一致所有 Railway 命令执行前会先校验railwayCLI 可用、项目名合法且 Wasp 项目目录存在setup与launch的 API 调用被包了一层retryOnRailwayAPIError以应对 Railway API 的瞬时错误。launch 命令自动注入的环境变量无论是 Fly.io 还是 Railway运行launch命令时Wasp CLI 都知道如何把 Wasp 应用的各部分连接起来因此会自动为你的服务端应用配置所需的环境变量详见 _launch-command-env-vars.mdWASP_WEB_CLIENT_URL和WASP_SERVER_URL连接客户端与服务端应用所必需DATABASE_URL连接服务端应用与数据库所必需JWT_SECRET认证功能正常工作所必需。在 Fly 的实现中参见 setup.ts这些变量通过flyctl secrets set注入const jwtSecret generateRandomHexString(); const secretsArgs [ JWT_SECRET${jwtSecret}, PORT${serverAppPort}, WASP_WEB_CLIENT_URL${getFlyAppUrl(deploymentInstructions.clientFlyAppName)}, WASP_SERVER_URL${getFlyAppUrl(deploymentInstructions.serverFlyAppName)}, ];可以看到JWT_SECRET由部署包自动生成随机十六进制字符串WASP_WEB_CLIENT_URL与WASP_SERVER_URL则根据 Fly 应用名推导出公网 URL你通过--server-secret传入的额外密钥会被追加进同一批secrets set调用。这些自动注入的变量配合你手动补充的社交登录等密钥共同构成了生产环境服务端所需的完整配置。总结与最佳实践Wasp Deploy 把注册服务 → 创建数据库 → 注入环境变量 → 构建镜像 → 发布上线这条冗长的部署链路压缩为一条命令是官方推荐的 Wasp 应用部署方式。围绕它形成几个关键实践首次部署用launch日常更新用deploylaunch会依次执行setupcreate-dbdeployFly或setupdeployRailway只应在全新项目上运行一次之后每次发布新版本只需运行deploy把生成的 TOML 文件纳入版本控制Fly 场景并善用--fly-toml-dir实现多环境dev/staging管理服务端密钥用--server-secret或secrets set管理客户端环境变量则在每次部署时通过终端会话传入并用package.json的deploy脚本固化避免遗忘配置自定义域名后务必同步更新WASP_WEB_CLIENT_URL以保证 CORS 配置正确注意各平台的命名约束Fly 应用名需全局唯一Railway 项目名需在个人账号下唯一且两者都只需执行一次setup/create-db。若想深入了解部署包的完整实现可继续阅读 waspc/data/packages/deploy 下的 TypeScript 源码Fly 与 Railway 的 provider 实现、命令定义与参数校验以及 Wasp.Project.Deployment 模块 中 Haskell 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），仅供参考
