Wasp 部署 launch 命令自动配置的环境变量全解析WASP_WEB_CLIENT_URL、WASP_SERVER_URL、DATABASE_URL 与 JWT_SECRET【免费下载链接】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 deploy fly launch或wasp deploy railway launch时Wasp CLI 会自动把 Wasp 应用的各个部件客户端、服务器、数据库、认证连接起来并在服务器上预先配置好一组必需的环境变量。本文以 Wasp 仓库中 version-0.19 部署文档的 launch 命令环境变量片段 为骨架结合 Fly.io 部署源码 与 Railway 部署源码 的实现细节逐一说明这四个环境变量的作用、取值规则与底层原理。读完本文你将清楚理解 launch 命令究竟“替你做了什么”以及部署后如何安全地补充或修改这些变量。launch 命令一次命令连接全栈应用的四个部件Wasp 应用由客户端React、服务器Node.js/Express、数据库PostgreSQL三部分构成外加认证系统。当你在生产环境运行launch命令时Wasp CLI 需要把这三部分“串”起来因此会自动为服务器应用设置以下环境变量WASP_WEB_CLIENT_URL和WASP_SERVER_URL—— 用于连接客户端应用与服务器应用DATABASE_URL—— 用于连接服务器应用与数据库JWT_SECRET—— 用于保证认证功能正常工作。在 version-0.19 的环境变量文档 中这组变量全部被标记为required必需也就是说缺少任何一个Wasp 服务器在启动时都会因环境变量校验失败而报错。launch命令的价值正在于此它把“需要手写四个正确取值”的繁琐工作变成了全自动。需要说明的是launch是setup、create-db、deploy等子命令的便捷组合其自动配置环境变量的逻辑实际实现在setup阶段。下面我们先逐一解析每个变量的用途再看底层源码是如何赋值与写入的。WASP_WEB_CLIENT_URL告诉服务器“客户端在哪里”作用服务器使用该值作为你的客户端 URL用于各类需要回链到前端页面的功能典型场景包括发送邮件时生成“点击此链接验证邮箱 / 重置密码”的跳转地址配置 CORS跨域资源共享决定允许哪些来源的前端请求访问服务器 API配合WASP_SERVER_URL完成 OAuth 登录后的跳转链路。类型与取值类型为 URL必填。在 Fly.io 上它的值形如https://my-wasp-app-client.fly.dev即客户端 Fly App 的公开 URL在 Railway 上则引用客户端服务的RAILWAY_PUBLIC_DOMAIN变量形如https://client-service.up.railway.app。从源码看服务器生成器在 ServerGenerator/Common.hs 中定义了环境变量名clientUrlEnvVarName :: String clientUrlEnvVarName WASP_WEB_CLIENT_URL后续生成 CORS 配置、邮件模板、OAuth 回调地址时都会读取这个变量。WASP_SERVER_URL告诉外部“服务器在哪里”作用服务器使用该值作为自身的公开 URL最典型的场景是OAuth 登录回调——当用户跳转到 Google / GitHub 授权页并授权后OAuth 提供方需要把用户重定向回一个确定的服务器地址这个地址就是WASP_SERVER_URL。此外它也用于生成指向服务器 API 的绝对链接。类型与取值类型为 URL必填。在 Fly.io 上它指向服务器 Fly App 的 URL如https://my-wasp-app-server.fly.dev在 Railway 上它引用服务器服务自身的RAILWAY_PUBLIC_DOMAIN注意引用自身服务时不加服务名前缀这一点在 Railway 源码中有明确注释。对应地服务器生成器在 ServerGenerator/Common.hs 中定义了serverUrlEnvVarName WASP_SERVER_URL这两个 URL 变量的存在解释了 Wasp 为何能在不知道“最终部署在哪个域名”的前提下仍然生成正确的 CORS、邮件与 OAuth 配置——因为真正取值发生在运行时由部署平台注入。DATABASE_URL连接服务器与数据库的生命线作用服务器应用通过该变量连接 PostgreSQL 数据库。缺少它任何读写数据库的操作Query、Action、Job都无法工作。类型与取值类型为字符串必填。典型取值为postgresql://user:passwordhost:5432/dbname形式的连接串在 Fly.io 上数据库由wasp deploy fly create-db创建随后通过flyctl把连接串写入服务器 App 的 Secrets在 Railway 上setup会创建一个名为Postgres的数据库服务然后把DATABASE_URL变量通过引用方式注入服务器服务源码使用getRailwayEnvVarValueReference(DATABASE_URL, { serviceName: dbServiceName })即变量值是对 Postgres 服务DATABASE_URL的引用而非硬编码的字符串。JWT_SECRET认证令牌的安全基石作用Wasp 使用 JWTJSON Web Token实现会话认证。JWT_SECRET是用于签名和校验令牌的密钥必须保密且足够随机——如果攻击者得知该值就能伪造用户令牌。类型与取值类型为字符串必填官方要求至少 32 字符的随机字符串。关键细节launch会自动为你生成一个随机 JWT_SECRET无需手动指定。这在两份平台源码中都有明确实现Fly.io 源码 setup.ts 中generateRandomHexString()生成随机十六进制串然后通过flyctl secrets set JWT_SECRET...写入服务器 AppRailway 源码 setup.ts 中同样用generateRandomHexString()生成后通过railway add --variables JWT_SECRET...注入服务器服务。服务器生成器在 ServerGenerator/AuthG.hs 中定义了该环境变量名jwtSecretEnvVarName JWT_SECRET注意生产环境的JWT_SECRET必须保持稳定。由于它由launch随机生成一次并持久化在部署平台上只要你不手动重置后续部署都会沿用同一密钥用户的登录状态不会失效。平台实现对比Fly.io 与 Railway 的赋值差异虽然两个平台的launch命令设置的环境变量集合相同但底层写入方式不同理解这点有助于排查部署问题环节Fly.ioRailway变量写入机制flyctl secrets set密钥存储写入后不可在配置中明文查看railway add --variables普通变量可在 Dashboard Variables 标签页查看/编辑服务端口服务器PORT8080客户端internal_port8043服务器PORT8080客户端PORT8043WASP_WEB_CLIENT_URL硬编码为客户端 App URL引用客户端服务RAILWAY_PUBLIC_DOMAINWASP_SERVER_URL硬编码为服务器 App URL引用服务器自身RAILWAY_PUBLIC_DOMAIN不带服务名前缀DATABASE_URLcreate-db创建后由 flyctl 注入引用Postgres服务的DATABASE_URLJWT_SECRET随机生成 flyctl secrets set随机生成 railway add --variables两份源码都展示了 Wasp CLI 的“最小惊讶”设计所有内置变量全部自动配置用户只需关心自己的业务变量。例如 Fly.io 的 setup 会先把min_machines_running修正为 1、把internal_port修正为 8080/8043再注入密钥Railway 的 setup 则会为客户端服务创建Staticfile并设置RAILPACK_STATIC_FILE_ROOT1确保 Railpack 把构建产物识别为静态站点。补充你的额外环境变量launch只负责内置变量。如果你的应用还需要其他变量需要按“服务端 / 客户端”两类分别处理服务端变量如社交登录密钥可以在launch/setup时通过--server-secret一次性传入可重复使用该选项# Fly.io wasp deploy fly launch my-wasp-app dfw \ --server-secret GOOGLE_CLIENT_ID... \ --server-secret GOOGLE_CLIENT_SECRET... # Railway wasp deploy railway launch my-wasp-app \ --server-secret GOOGLE_CLIENT_ID... \ --server-secret GOOGLE_CLIENT_SECRET...应用部署完成后也可以事后补设wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID... GOOGLE_CLIENT_SECRET... --contextserverRailway 则直接在 Dashboard 中进入服务器服务的Variables标签页添加即可。从源码看--server-secret提供的变量会原样追加到内置变量之后FlysecretsArgs.push(secret)Railway...options.serverSecret.map(...)因此它们与内置变量同等对待。客户端变量如REACT_APP_*客户端变量是在构建期注入 JS 代码的因此必须在运行部署命令的终端会话中显式传入且每次部署都要传REACT_APP_ANOTHER_VARsomevalue wasp deploy fly launch my-wasp-app dfw REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy my-wasp-app为避免遗忘官方建议在package.json中固化一个 deploy 脚本{ scripts: { deploy: REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy } }注意客户端变量是公开的任何访问网站的人都能在浏览器中看到严禁存放密钥服务端变量才适合存放秘密。更完整的变量清单含 SMTP、SendGrid、Mailgun、OAuth、PG_BOSS_NEW_OPTIONS等可查阅 project/env-vars.md。自定义域名后必须更新 WASP_WEB_CLIENT_URL接入自定义域名时launch自动配置的WASP_WEB_CLIENT_URL就不再指向你的正式域名此时需要手动更新否则会导致CORS 错误浏览器拒绝来自新域名前端发起的 API 请求。Fly.io 上的做法是wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URLhttps://mycoolapp.comRailway 上则是在 Dashboard 的服务器服务Variables标签页中把WASP_WEB_CLIENT_URL更新为新域名。这正是WASP_WEB_CLIENT_URL必须由服务器持有、并参与 CORS 配置校验的原因——官方注释明确写着“我们需要这样做以保持 CORS 配置最新”。开发环境 vs 生产环境环境变量的两种形态理解launch自动配置的前提是知道开发与生产环境下环境变量的注入方式完全不同开发环境wasp start推荐在项目根目录使用.env.server与.env.client两个 dotenv 文件分别提供给服务器与客户端Shell 中预置的变量优先级更高可用于临时覆盖。生产环境launch/deploy由托管平台的机制注入——Fly.io 使用 Secrets 存储Railway 使用 Variables 引用。值得留意的是开发环境下 Wasp 会为WASP_WEB_CLIENT_URL、WASP_SERVER_URL等内置变量提供合理的本地默认值如服务器默认监听PORT3001、客户端默认通过REACT_APP_API_URL指向http://localhost:3001所以本地开发几乎不需要手动设置这些变量而生产环境因为 URL 未知必须由launch自动生成并注入。小结wasp deploy fly launch与wasp deploy railway launch之所以能“一条命令完成部署”关键在于 Wasp CLI 自动把应用解耦的四块拼图——前端、后端、数据库、认证——用四个环境变量重新缝合起来WASP_WEB_CLIENT_URLWASP_SERVER_URL连接客户端与服务器CORS、邮件链接、OAuth 回调DATABASE_URL连接服务器与数据库JWT_SECRET认证令牌的签名密钥自动随机生成。如果你在此基础上继续深入可以进一步阅读 Fly.io 完整部署指南含区域选择、多组织--org、自定义数据库镜像、fly-server.toml/fly-client.toml说明与 Railway 完整部署指南含--existing-project-id、--workspace、--skip-client/--skip-server等选项并对照部署 SDK 源码 fly/commands/setup/setup.ts 与 railway/commands/setup/setup.ts 理解每一条变量的注入时机。理解这套环境变量约定是后续排查部署、配置 OAuth、接入自定义域名时少走弯路的关键。【免费下载链接】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），仅供参考
Wasp 部署 launch 命令自动配置的环境变量全解析：WASP_WEB_CLIENT_URL、WASP_SERVER_URL、DATABASE_URL 与 JWT_SECRET
Wasp 部署 launch 命令自动配置的环境变量全解析WASP_WEB_CLIENT_URL、WASP_SERVER_URL、DATABASE_URL 与 JWT_SECRET【免费下载链接】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 deploy fly launch或wasp deploy railway launch时Wasp CLI 会自动把 Wasp 应用的各个部件客户端、服务器、数据库、认证连接起来并在服务器上预先配置好一组必需的环境变量。本文以 Wasp 仓库中 version-0.19 部署文档的 launch 命令环境变量片段 为骨架结合 Fly.io 部署源码 与 Railway 部署源码 的实现细节逐一说明这四个环境变量的作用、取值规则与底层原理。读完本文你将清楚理解 launch 命令究竟“替你做了什么”以及部署后如何安全地补充或修改这些变量。launch 命令一次命令连接全栈应用的四个部件Wasp 应用由客户端React、服务器Node.js/Express、数据库PostgreSQL三部分构成外加认证系统。当你在生产环境运行launch命令时Wasp CLI 需要把这三部分“串”起来因此会自动为服务器应用设置以下环境变量WASP_WEB_CLIENT_URL和WASP_SERVER_URL—— 用于连接客户端应用与服务器应用DATABASE_URL—— 用于连接服务器应用与数据库JWT_SECRET—— 用于保证认证功能正常工作。在 version-0.19 的环境变量文档 中这组变量全部被标记为required必需也就是说缺少任何一个Wasp 服务器在启动时都会因环境变量校验失败而报错。launch命令的价值正在于此它把“需要手写四个正确取值”的繁琐工作变成了全自动。需要说明的是launch是setup、create-db、deploy等子命令的便捷组合其自动配置环境变量的逻辑实际实现在setup阶段。下面我们先逐一解析每个变量的用途再看底层源码是如何赋值与写入的。WASP_WEB_CLIENT_URL告诉服务器“客户端在哪里”作用服务器使用该值作为你的客户端 URL用于各类需要回链到前端页面的功能典型场景包括发送邮件时生成“点击此链接验证邮箱 / 重置密码”的跳转地址配置 CORS跨域资源共享决定允许哪些来源的前端请求访问服务器 API配合WASP_SERVER_URL完成 OAuth 登录后的跳转链路。类型与取值类型为 URL必填。在 Fly.io 上它的值形如https://my-wasp-app-client.fly.dev即客户端 Fly App 的公开 URL在 Railway 上则引用客户端服务的RAILWAY_PUBLIC_DOMAIN变量形如https://client-service.up.railway.app。从源码看服务器生成器在 ServerGenerator/Common.hs 中定义了环境变量名clientUrlEnvVarName :: String clientUrlEnvVarName WASP_WEB_CLIENT_URL后续生成 CORS 配置、邮件模板、OAuth 回调地址时都会读取这个变量。WASP_SERVER_URL告诉外部“服务器在哪里”作用服务器使用该值作为自身的公开 URL最典型的场景是OAuth 登录回调——当用户跳转到 Google / GitHub 授权页并授权后OAuth 提供方需要把用户重定向回一个确定的服务器地址这个地址就是WASP_SERVER_URL。此外它也用于生成指向服务器 API 的绝对链接。类型与取值类型为 URL必填。在 Fly.io 上它指向服务器 Fly App 的 URL如https://my-wasp-app-server.fly.dev在 Railway 上它引用服务器服务自身的RAILWAY_PUBLIC_DOMAIN注意引用自身服务时不加服务名前缀这一点在 Railway 源码中有明确注释。对应地服务器生成器在 ServerGenerator/Common.hs 中定义了serverUrlEnvVarName WASP_SERVER_URL这两个 URL 变量的存在解释了 Wasp 为何能在不知道“最终部署在哪个域名”的前提下仍然生成正确的 CORS、邮件与 OAuth 配置——因为真正取值发生在运行时由部署平台注入。DATABASE_URL连接服务器与数据库的生命线作用服务器应用通过该变量连接 PostgreSQL 数据库。缺少它任何读写数据库的操作Query、Action、Job都无法工作。类型与取值类型为字符串必填。典型取值为postgresql://user:passwordhost:5432/dbname形式的连接串在 Fly.io 上数据库由wasp deploy fly create-db创建随后通过flyctl把连接串写入服务器 App 的 Secrets在 Railway 上setup会创建一个名为Postgres的数据库服务然后把DATABASE_URL变量通过引用方式注入服务器服务源码使用getRailwayEnvVarValueReference(DATABASE_URL, { serviceName: dbServiceName })即变量值是对 Postgres 服务DATABASE_URL的引用而非硬编码的字符串。JWT_SECRET认证令牌的安全基石作用Wasp 使用 JWTJSON Web Token实现会话认证。JWT_SECRET是用于签名和校验令牌的密钥必须保密且足够随机——如果攻击者得知该值就能伪造用户令牌。类型与取值类型为字符串必填官方要求至少 32 字符的随机字符串。关键细节launch会自动为你生成一个随机 JWT_SECRET无需手动指定。这在两份平台源码中都有明确实现Fly.io 源码 setup.ts 中generateRandomHexString()生成随机十六进制串然后通过flyctl secrets set JWT_SECRET...写入服务器 AppRailway 源码 setup.ts 中同样用generateRandomHexString()生成后通过railway add --variables JWT_SECRET...注入服务器服务。服务器生成器在 ServerGenerator/AuthG.hs 中定义了该环境变量名jwtSecretEnvVarName JWT_SECRET注意生产环境的JWT_SECRET必须保持稳定。由于它由launch随机生成一次并持久化在部署平台上只要你不手动重置后续部署都会沿用同一密钥用户的登录状态不会失效。平台实现对比Fly.io 与 Railway 的赋值差异虽然两个平台的launch命令设置的环境变量集合相同但底层写入方式不同理解这点有助于排查部署问题环节Fly.ioRailway变量写入机制flyctl secrets set密钥存储写入后不可在配置中明文查看railway add --variables普通变量可在 Dashboard Variables 标签页查看/编辑服务端口服务器PORT8080客户端internal_port8043服务器PORT8080客户端PORT8043WASP_WEB_CLIENT_URL硬编码为客户端 App URL引用客户端服务RAILWAY_PUBLIC_DOMAINWASP_SERVER_URL硬编码为服务器 App URL引用服务器自身RAILWAY_PUBLIC_DOMAIN不带服务名前缀DATABASE_URLcreate-db创建后由 flyctl 注入引用Postgres服务的DATABASE_URLJWT_SECRET随机生成 flyctl secrets set随机生成 railway add --variables两份源码都展示了 Wasp CLI 的“最小惊讶”设计所有内置变量全部自动配置用户只需关心自己的业务变量。例如 Fly.io 的 setup 会先把min_machines_running修正为 1、把internal_port修正为 8080/8043再注入密钥Railway 的 setup 则会为客户端服务创建Staticfile并设置RAILPACK_STATIC_FILE_ROOT1确保 Railpack 把构建产物识别为静态站点。补充你的额外环境变量launch只负责内置变量。如果你的应用还需要其他变量需要按“服务端 / 客户端”两类分别处理服务端变量如社交登录密钥可以在launch/setup时通过--server-secret一次性传入可重复使用该选项# Fly.io wasp deploy fly launch my-wasp-app dfw \ --server-secret GOOGLE_CLIENT_ID... \ --server-secret GOOGLE_CLIENT_SECRET... # Railway wasp deploy railway launch my-wasp-app \ --server-secret GOOGLE_CLIENT_ID... \ --server-secret GOOGLE_CLIENT_SECRET...应用部署完成后也可以事后补设wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID... GOOGLE_CLIENT_SECRET... --contextserverRailway 则直接在 Dashboard 中进入服务器服务的Variables标签页添加即可。从源码看--server-secret提供的变量会原样追加到内置变量之后FlysecretsArgs.push(secret)Railway...options.serverSecret.map(...)因此它们与内置变量同等对待。客户端变量如REACT_APP_*客户端变量是在构建期注入 JS 代码的因此必须在运行部署命令的终端会话中显式传入且每次部署都要传REACT_APP_ANOTHER_VARsomevalue wasp deploy fly launch my-wasp-app dfw REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy my-wasp-app为避免遗忘官方建议在package.json中固化一个 deploy 脚本{ scripts: { deploy: REACT_APP_ANOTHER_VARsomevalue wasp deploy railway deploy } }注意客户端变量是公开的任何访问网站的人都能在浏览器中看到严禁存放密钥服务端变量才适合存放秘密。更完整的变量清单含 SMTP、SendGrid、Mailgun、OAuth、PG_BOSS_NEW_OPTIONS等可查阅 project/env-vars.md。自定义域名后必须更新 WASP_WEB_CLIENT_URL接入自定义域名时launch自动配置的WASP_WEB_CLIENT_URL就不再指向你的正式域名此时需要手动更新否则会导致CORS 错误浏览器拒绝来自新域名前端发起的 API 请求。Fly.io 上的做法是wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URLhttps://mycoolapp.comRailway 上则是在 Dashboard 的服务器服务Variables标签页中把WASP_WEB_CLIENT_URL更新为新域名。这正是WASP_WEB_CLIENT_URL必须由服务器持有、并参与 CORS 配置校验的原因——官方注释明确写着“我们需要这样做以保持 CORS 配置最新”。开发环境 vs 生产环境环境变量的两种形态理解launch自动配置的前提是知道开发与生产环境下环境变量的注入方式完全不同开发环境wasp start推荐在项目根目录使用.env.server与.env.client两个 dotenv 文件分别提供给服务器与客户端Shell 中预置的变量优先级更高可用于临时覆盖。生产环境launch/deploy由托管平台的机制注入——Fly.io 使用 Secrets 存储Railway 使用 Variables 引用。值得留意的是开发环境下 Wasp 会为WASP_WEB_CLIENT_URL、WASP_SERVER_URL等内置变量提供合理的本地默认值如服务器默认监听PORT3001、客户端默认通过REACT_APP_API_URL指向http://localhost:3001所以本地开发几乎不需要手动设置这些变量而生产环境因为 URL 未知必须由launch自动生成并注入。小结wasp deploy fly launch与wasp deploy railway launch之所以能“一条命令完成部署”关键在于 Wasp CLI 自动把应用解耦的四块拼图——前端、后端、数据库、认证——用四个环境变量重新缝合起来WASP_WEB_CLIENT_URLWASP_SERVER_URL连接客户端与服务器CORS、邮件链接、OAuth 回调DATABASE_URL连接服务器与数据库JWT_SECRET认证令牌的签名密钥自动随机生成。如果你在此基础上继续深入可以进一步阅读 Fly.io 完整部署指南含区域选择、多组织--org、自定义数据库镜像、fly-server.toml/fly-client.toml说明与 Railway 完整部署指南含--existing-project-id、--workspace、--skip-client/--skip-server等选项并对照部署 SDK 源码 fly/commands/setup/setup.ts 与 railway/commands/setup/setup.ts 理解每一条变量的注入时机。理解这套环境变量约定是后续排查部署、配置 OAuth、接入自定义域名时少走弯路的关键。【免费下载链接】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），仅供参考