Wasp 单命令全栈部署指南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本篇指南围绕 Wasp 框架官方推荐的自动化部署方式wasp deploy展开讲解如何用一条命令把 Wasp 全栈应用React 客户端 Node.js 服务端 PostgreSQL 数据库部署到 Fly.io 或 Railway并深入剖析launch命令背后自动化的服务创建、构建、部署流程以及环境变量、自定义域名、CI/CD 集成等实战细节。读完本文你将掌握 Wasp 应用从本地开发到云端上线的完整闭环并理解其底层实现原理。wasp deploy是什么Wasp 的部署命令在设计上有两个核心目标把手工部署流程自动化并成为 Wasp 应用官方推荐的部署方式。与手工在云平台上创建服务、配置数据库、构建镜像、设置环境变量的繁琐过程相比wasp deploy由 Wasp CLI 一键接管全部环节。它的用法非常简洁wasp deploy provider launch my-wasp-app这条命令会完成三件事在目标云平台上创建应用所需的全部服务客户端、服务端、数据库构建你的 Wasp 应用包括客户端与服务端把构建产物部署上线。从仓库源码可以看到wasp deploy子命令体系定义在 waspc/data/packages/deploy/src/index.ts入口程序注册了两个 provider 子命令fly与railway整个部署 CLI 基于commander构建并透传了--wasp-exe与--wasp-project-dir两个隐藏参数来定位 Wasp 可执行文件与项目目录program .name(wasp deploy) .description(CLI for deploying Wasp apps to various clouds) .allowUnknownOption(); program.addCommand(createFlyCommand()); program.addCommand(createRailwayCommand());支持的部署平台Wasp Deploy 目前支持以下两个自动化部署平台对应文档页面 Fly.io 与 RailwayFly.io面向全球的容器化应用运行平台可把应用部署在世界各地的数据中心通过 Anycast 网络就近响应用户Railway自带数据库与服务编排能力的云端开发平台界面直观、基础设施自动化程度高。两个平台的 CLI 命令结构完全对称均为wasp deploy provider 子命令 [参数]学习成本很低。理解launch命令背后的自动化流程launch是wasp deploy最常用的一键上线命令但它本质上是一个组合命令内部按顺序调用了多个子命令。搞清楚这一点你就能在需要分步执行例如先建库、再单独发布时得心应手。Fly.io 上的launch对 Fly.io 而言wasp deploy fly launch app-name region等价于依次执行wasp deploy fly setup app-name region wasp deploy fly create-db region wasp deploy fly deploy即注册服务 → 创建数据库 → 部署上线。在源码 waspc/data/packages/deploy/src/providers/fly/commands/launch/launch.ts 中可以看到这一调用链的直接实现——launch()依次调用setup()、createDb()和deploy()并且会先检查项目里是否已存在fly-server.toml/fly-client.toml若已存在则直接报错提醒你launch只应在全新 Fly 项目上运行一次。Railway 上的launch对 Railway 而言wasp deploy railway launch project-name等价于wasp deploy railway setup project-name wasp deploy railway deploy project-name区别在于 Railway 的数据库服务由setup一并创建无需单独的create-db子命令。launch自动配置的环境变量运行launch命令时Wasp CLI 已经知道你的 Wasp 应用各部分组成会自动为服务端应用设置以下关键环境变量这也是全栈应用能在云上正常连通的关键环境变量作用WASP_WEB_CLIENT_URL客户端应用地址客户端与服务端连通所必需WASP_SERVER_URL服务端应用地址客户端与服务端连通所必需DATABASE_URL数据库连接串服务端连接数据库所必需JWT_SECRET认证密钥Wasp 认证功能正常工作所必需除此之外如果你的应用还需要其他服务端环境变量如 Google 登录的GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET可以在launch或setup命令中通过--server-secret FOOBAR传入客户端环境变量则需要在运行部署命令前以环境变量的形式注入当前终端会话详见下文对应平台小节。关于客户端环境变量的完整说明可参考 env-vars 文档。部署到 Fly.ioFly.io 适合希望把应用就近部署到全球多个数据中心、并享受成熟容器化生态的场景。以下内容完整对应 Fly.io 部署文档。前置条件在开始之前你需要准备一个 Fly.io 账户注意Fly 要求先绑定支付方式才能部署超过两个应用而一个 Wasp 应用需要三个 Fly 应用客户端-client、服务端-server、数据库-db因此绑卡是必需步骤在本地安装flyCLI。发起部署一条命令完成上线wasp deploy fly launch my-wasp-app dfw建议命令运行期间不要 Ctrl-C 或关闭终端等待全部步骤执行完毕。需要牢记两点应用名如my-wasp-app在整个 Fly 平台范围内必须唯一否则部署会失败如果你的 Fly 账户属于多个组织需要额外指定--org org-slug参数可用fly orgs list查看你的组织 slug 列表。上述命令中my-wasp-app作为 basename应用基名dfw是部署区域dfw即美国德克萨斯州达拉斯。Wasp 会用这个基名创建三个独立应用它们会同时出现在你的 Fly 控制台中my-wasp-app-clientmy-wasp-app-servermy-wasp-app-db生成的两个 TOML 配置文件部署成功后Wasp 会在项目根目录生成两个新文件fly-server.tomlfly-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-client.toml 结构相同只是服务名、内部端口客户端为8043和min_machines_running客户端可为0有所不同。你可以直接编辑这两个 TOML 文件来进一步定制 Fly 部署如调整 VM 规格Wasp 在deploy时会读取它们。若需要同时维护多个应用如dev、staging环境可用--fly-toml-dir 绝对路径指向不同的目录。从源码看TOML 文件的读写逻辑集中在 waspc/data/packages/deploy/src/providers/fly/tomlFile.ts部署时会把项目里的fly-server.toml/fly-client.toml复制为当前目录的fly.toml交给 flyctl 使用再从中解析出app名称反推 basename。配置自定义域名为应用绑定自定义域名共三步以下命令中的mycoolapp.com请替换为你自己的域名第一步为 Fly 客户端应用创建证书wasp deploy fly cmd --context client certs create 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环境变量保持 CORS 配置与域名一致wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URLhttps://mycoolapp.com完成以上三步应用即可通过https://mycoolapp.com访问。添加www子域名若还希望支持https://www.mycoolapp.com先为www子域生成证书wasp deploy fly cmd --context client certs create www.mycoolapp.com再为www添加一条指向根域的 CNAME 记录TypeNameValueTTLCNAMEwwwmycoolapp.com3600注意同时使用www与non-www两个域名时必须更新服务端的 CORS 配置以同时允许两个域名否则会出现跨域错误。服务端与客户端环境变量服务端密钥除了launch/setup时用--server-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 dfw或REACT_APP_ANOTHER_VARsomevalue wasp deploy fly deploy注意每次部署都必须带上而不只是首次。为避免遗忘建议在package.json中固化一个部署脚本{ scripts: { deploy: REACT_APP_ANOTHER_VARsomevalue wasp deploy fly deploy } }之后运行npm run deploy即可完成部署。选择部署区域Fly.io 在全球 34 个区域运行应用并通过 Anycast 网络让用户就近接入。可通过如下命令查看所有可用区域fly platform regions在launch命令中区域参数必须是三位字母代码源码中会统一转为小写并校验合法性如dfw达拉斯、cdg巴黎等。多组织场景多组织账户可显式指定组织wasp deploy fly launch my-wasp-app dfw --org hive本地构建与远程构建Fly.io 同时支持本地构建与远程构建 Docker 容器。为了简单与可复现CLI 默认使用Fly 远程构建器。如需本地构建为launch或deploy增加--build-locally选项即可。使用自定义 PostgreSQL 数据库Wasp 默认使用 PostgreSQL 18与开发环境主版本一致创建 Fly 数据库镜像为flyio/postgres-flex:18该默认值定义在 waspc/data/packages/deploy/src/providers/fly/index.ts 中并刻意与 Wasp 开发数据库的主版本保持同步。若应用需要其他 PostgreSQL 镜像例如添加 PostGIS 扩展使用--db-image docker-image指定。自定义镜像必须与 Fly 平台兼容最稳妥的做法是基于官方镜像flyio/postgres-flex构建。数据库镜像只需在创建数据库时指定一次wasp deploy fly create-db region --db-image custom-postgres-image wasp deploy fly launch app-name region --db-image custom-postgres-imageFly.io 命令速查API Referencelaunch一键完成setupcreate-dbdeploy。wasp deploy fly launch app-name regionapp-name必填应用名region必填部署区域。launch支持数据库选项见下、--server-secret/--client-secret、--build-locally以及--custom-server-url当客户端需要连接不同服务端地址、例如服务端使用自定义域名时使用。setup在 Fly 上注册客户端与服务端应用并配置环境变量。只执行一次不会触发部署wasp deploy fly setup app-name regionapp-name必填、region必填运行后会生成fly-server.toml与fly-client.toml请纳入版本控制多应用场景可用--fly-toml-dir abs-path指向不同目录注意setup每个应用只能执行一次重复执行会在 Fly 上创建多余应用。create-db为应用创建数据库每个应用只需一次wasp deploy fly create-db regionregion必填重复执行会创建多个数据库而应用只需要一个。deploy将构建好的客户端与服务端推送上线用于更新已部署应用wasp deploy fly deploy支持--skip-client不部署客户端、--skip-server不部署服务端、--build-locally与--custom-server-url。cmd在客户端或服务端上下文中执行任意 flyctl 命令wasp deploy fly cmd secrets list --context server必须通过--context指定client或server。Fly 数据库选项一览所有数据库选项均为可选项选项默认值说明--db-vm-size vmSizeshared-cpu-1x数据库 VM 规格决定 CPU 种类、核数与内存--db-vm-memory vmMemory由 VM 规格决定数据库 VM 内存MB--db-vm-cpus vmCpus由 VM 规格决定数据库 VM CPU 核数--db-vm-cpu-kind vmCpuKind由 VM 规格决定数据库 VM CPU 种类--db-initial-cluster-size size1数据库初始机器数量--db-volume-size size1数据库卷大小GB--db-image imageflyio/postgres-flex:18PostgreSQL Docker 镜像部分应用需要比 Fly 默认更高的数据库内存此时请在创建数据库时使用--db-vm-memory。注意 Fly 只接受特定组合的 CPU 种类、核数与内存自定义时要参照 Fly 的机器规格规则选择匹配的值。部署到 RailwayRailway 提供开箱即用的数据库与服务编排能力适合追求界面化操作与快速上手的场景。以下内容完整对应 Railway 部署文档。前置条件注册 Railway 账户在本地安装railwayCLI。发起部署wasp deploy railway launch my-wasp-app注意事项项目名如my-wasp-app在你的 Railway 账户内必须唯一否则部署失败这是当前 Wasp CLI 与 Railway 集成的一个已知限制如果你属于多个 Railway 组织CLI 会提示你选择部署目标组织。项目名会作为客户端与服务端服务名的基名my-wasp-app-clientmy-wasp-app-server数据库服务则固定命名为Postgres与项目名无关。配置自定义域名第一步在 Railway 控制台为客户端服务添加域名进入 Railway dashboard选择项目如my-wasp-app点击客户端服务如my-wasp-app-client进入Settings标签页点击Custom Domain输入域名如mycoolapp.com与端口8080点击Add Domain。第二步更新 DNS 记录为域名添加一条 CNAME 记录指向上一步获得的地址具体操作取决于你的域名服务商。第三步为避免 CORS 错误在 Railway 控制台的服务端服务my-wasp-app-server的Variables标签页中将WASP_WEB_CLIENT_URL更新为新的客户端地址如https://mycoolapp.com。完成以上步骤应用即可通过https://mycoolapp.com访问。Railway 命令速查API Referencelaunch一键完成setupdeploywasp deploy railway launch project-nameproject-name必填项目名。launch支持以下扩展选项--existing-project-id railway-project-id默认情况下 Wasp CLI 会新建名为project-name的 Railway 项目若想复用已有项目传入其 ID--workspace railway-workspace-id-or-name默认会交互式询问工作区可用此参数跳过提示直接指定--server-secret FOOBAR设置服务端密钥--db-image docker-image与--db-volume-mount-path path自定义 PostgreSQL 数据库--custom-server-url https://api.myapp.com自定义服务端地址。deploy部署或更新客户端与服务端wasp deploy railway deploy project-name会使用与 Wasp 项目目录关联的 Railway 项目若尚未关联命令会失败并提示先运行setupCI 场景可用--existing-project-id railway-project-id显式指定项目 ID支持--skip-client不部署客户端与--skip-server不部署服务端。setup创建客户端、服务端与数据库服务并配置环境变量。不会触发部署wasp deploy railway setup project-name服务命名为project-name-client与project-name-server同时创建名为Postgres的 PostgreSQL 数据库服务同样支持--existing-project-id与--workspace注意setup每个应用只需执行一次已存在的服务会被跳过不会重复创建。Railway 环境变量服务端密钥可在launch/setup时用--server-secret设置应用上线后也可在 Railway 控制台服务端服务的Variables标签页补充。客户端环境变量与 Fly 一致需要在每次运行部署命令前注入终端会话REACT_APP_ANOTHER_VARsomevalue wasp deploy railway launch my-wasp-app同样建议写入package.json的部署脚本避免遗忘{ scripts: { deploy: REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy } }Railway 自定义 PostgreSQLWasp 默认用 PostgreSQL 18 创建 Railway 数据库与开发环境主版本一致默认镜像为ghcr.io/railwayapp-templates/postgres-ssl:18默认已内置 pgvector数据存放在 Railway volume 中挂载路径默认/var/lib/postgresql/data可通过--db-volume-mount-path修改。需要 PostGIS 等扩展时wasp deploy railway launch my-wasp-app --db-image postgis/postgis:18-3.6镜像只需在首次创建应用时指定一次。另外这些命令创建的数据库无法使用 Railway 的 Database View 界面如需浏览数据可参考 连接生产数据库 文档用wasp db studio直连生产库。结合 CI/CD 实现提交即部署wasp deploy provider launch在本地完成首次部署后就可以在 CI/CD 流水线中用wasp deploy provider deploy实现每次推送自动重新部署。完整方案见 CI/CD 部署文档核心流程包括检出代码 → 安装 Node.js 与 Wasp CLI → 安装平台相关依赖如 flyctl / railway CLI→ 执行deploy命令并在 CI 中配置平台 API Token。Fly.io 的 CI 配置需要组织级 tokenfly tokens create org生成存入仓库 secrets 的FLY_API_TOKENname: Wasp Deploy on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest env: WASP_VERSION: {pinnedLatestWaspVersion} steps: - uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: {minimumNodeJsVersion} - name: Install Wasp run: npm i -g wasp.sh/wasp-cli$WASP_VERSION - name: Install Flyctl uses: superfly/flyctl-actions/setup-flyctlmaster - name: Deploy run: wasp deploy fly deploy env: FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}Railway 的 CI 配置需要账户 token在账户设置 Tokens 中生成不绑定工作区存入RAILWAY_API_TOKEN并将RAILWAY_PROJECT_NAME与RAILWAY_PROJECT_ID配置到环境name: Wasp Deploy on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest env: WASP_VERSION: {pinnedLatestWaspVersion} RAILWAY_PROJECT_NAME: my-project-name RAILWAY_PROJECT_ID: MY_PROJECT_ID steps: - uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: {minimumNodeJsVersion} - name: Install Wasp run: npm i -g wasp.sh/wasp-cli$WASP_VERSION - name: Install Railway CLI run: npm install -g railway/cli - name: Deploy run: wasp deploy railway deploy $RAILWAY_PROJECT_NAME --existing-project-id $RAILWAY_PROJECT_ID env: RAILWAY_API_TOKEN: ${{ secrets.RAILWAY_API_TOKEN }}建议将 Wasp CLI 版本固定如上例的$WASP_VERSION避免新版本发布带来的意外变更。从源码看wasp deploy的实现原理部署 CLI 的实现位于 waspc/data/packages/deploy/src整体结构清晰可作为理解其原理的入口命令入口index.ts用commander组装fly与railway两个 provider 子命令Fly 命令定义providers/fly/index.ts定义了launch/setup/create-db/deploy/cmd五个子命令及其全部选项。可以观察到几个设计细节默认数据库镜像被刻意固定为flyio/postgres-flex:18与 Wasp 开发数据库主版本保持一致避免 flyctl 服务端默认镜像跨大版本升级带来的不兼容每个子命令都通过preAction钩子先执行ensureFlyReady()确保本地 flyctl 可用、assertValidWaspProject()校验当前目录是合法 Wasp 项目以及区域合法性校验launch的组合语义、--build-locally默认远程构建、--org、--fly-toml-dir、--skip-client/--skip-server等选项都在这里注册Railway 命令定义providers/railway/index.ts结构上与 Fly 对称默认数据库镜像为ghcr.io/railwayapp-templates/postgres-ssl:18并额外提供--db-volume-mount-path选项TOML 文件管理providers/fly/tomlFile.ts负责fly.toml与项目内fly-server.toml/fly-client.toml之间的复制、解析app名称并反推 basename——这就是生成两个 TOML 文件并纳入版本控制后即可反复部署的底层机制。理解了这些源码你就能明白wasp deploy本质上是把flyctl / railway CLI 手工操作 Wasp 构建 环境变量编排封装为一条声明式的命令而launch的组合语义与 TOML 文件约定则是保证一次上线、多次更新可复现的关键设计。总结wasp deploy provider launch app-name是 Wasp 官方推荐的部署方式一条命令完成服务创建、应用构建与上线目前支持 Fly.io 与 Railway 两个平台命令体系对称launch均为组合命令可拆解为setup/create-db/deploy等原子步骤部署时自动配置WASP_WEB_CLIENT_URL、WASP_SERVER_URL、DATABASE_URL、JWT_SECRET四个关键环境变量其余服务端密钥用--server-secret或secrets set设置客户端变量需在每次部署时注入终端自定义域名、数据库规格、构建方式等均有对应的 CLI 选项支持且生成的 TOML 文件可纳入版本控制实现可复现部署首次launch之后即可在 CI/CD 中通过wasp deploy provider 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），仅供参考