Wasp 访问应用配置详解Server 与 Client 配置对象、环境变量及源码级实现解析v0.14【免费下载链接】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.14 版《Accessing the configuration》web/versioned_docs/version-0.14/advanced/accessing-app-config.md系统讲解 Wasp 应用启动后“客户端 服务端”双进程模型如何各自通过环境变量完成配置、如何通过config对象在运行时读取这些配置并结合 waspc 代码生成器模板深入解析frontendUrl与apiUrl的底层来源、CORS 派生逻辑及其在邮件链接、OAuth 重定向、WebSocket 等场景中的真实用法。读完本文你将掌握 Wasp 应用中前后端互相感知的完整配置链路并能独立排查部署时 URL 配置错误导致的 CORS 或回调失败问题。1. 运行模型启动一个 Wasp 应用就是启动两个进程文档开篇即指出核心事实Whenever you start a Wasp app, you are starting two processes每次启动 Wasp 应用实际上是在启动两个进程客户端进程client process——一个实现应用前端的 React 应用。开发阶段wasp start它是一个带热重载hot reloading的 dev server生产阶段它只是一个提供预构建静态文件的简单进程环境变量在构建期被嵌入具体行为取决于部署方式。服务端进程server process——一个实现应用后端的 Express 服务器。开发阶段它由nodemon进程托管负责热重载与重启生产阶段则是用 Node 直接运行的普通 Express 服务器。Wasp 运行时架构的更详细解释见官方介绍文档。这两个进程都可以通过环境变量进行配置支持的完整变量列表见部署文档的环境变量章节与环境变量专题文档。在此基础上Wasp 提供了配置对象configuration objects让你在运行时直接访问两个进程的已解析配置而不必到处读原始环境变量。2. 服务端配置对象config.frontendUrl服务端配置对象server configuration object包含字段frontendUrlfrontendUrl: String—— 通过环境变量WASP_WEB_CLIENT_URL设置表示客户端前端的 URL。开发阶段运行wasp start时由 Wasp自动设置无需手动填写生产阶段应将其设置为服务端视角下的客户端 URL即考虑了 DNS 与代理之后的地址例如公网域名。访问方式import { config } from wasp/server console.log(config.frontendUrl)2.1 源码级实现frontendUrl从哪里来wasp/server导出的config是由 waspc 代码生成器在编译期生成的。查看模板 waspc/data/Generator/templates/sdk/wasp/server/config.tsconst frontendUrl stripTrailingSlash(env[WASP_WEB_CLIENT_URL]) const serverUrl stripTrailingSlash(env[WASP_SERVER_URL]) const allowedCORSOriginsPerEnv: RecordNodeEnv, Config[allowedCORSOrigins] { development: [/.*/], production: [getOrigin(frontendUrl)] } const allowedCORSOrigins allowedCORSOriginsPerEnv[env.NODE_ENV] const config: Config { frontendUrl, serverUrl, allowedCORSOrigins, env: env.NODE_ENV, isDevelopment: env.NODE_ENV development, port: env.PORT, databaseUrl: env.DATABASE_URL, auth: { jwtSecret: env.JWT_SECRET // 仅在启用 auth 时生成 } }从源码结构看可以确认几个关键细节环境变量名是硬编码约定WASP_WEB_CLIENT_URL与WASP_SERVER_URL这两个名称定义在生成器常量 waspc/src/Wasp/Generator/ServerGenerator/Common.hs 中clientUrlEnvVarName WASP_WEB_CLIENT_URL模板中的{ clientUrlEnvVarName }占位符在生成时被替换为该常量。因此这两个变量名在任意版本的 Wasp 中都是稳定的契约。尾斜杠会被自动剥离stripTrailingSlash所以生产配置中写https://myapp.com/或https://myapp.com都不会破坏后续拼接逻辑。生产环境的 CORS 白名单直接由frontendUrl派生allowedCORSOrigins取frontendUrl的 origin。这意味着WASP_WEB_CLIENT_URL配置错误例如漏配、写成内网地址在生产环境会直接导致浏览器 CORS 拒绝跨域请求——这是部署时最常见的 URL 相关故障点。开发环境则放开为/.*/匹配任意来源。2.2frontendUrl在框架内部的真实用途config.frontendUrl不只是给用户打印的Wasp 运行时内部多处依赖它构造“服务端 → 客户端”的跳转地址OAuth 回调重定向waspc/data/Generator/templates/sdk/wasp/server/auth/oauth/redirect.ts 用${config.frontendUrl}${clientOAuthCallbackPath}#${oneTimeCode}生成浏览器回跳地址出错时同样拼接到?error上。邮件中的验证/重置链接waspc/data/Generator/templates/sdk/wasp/server/auth/email/utils.ts 以${waspServerConfig.frontendUrl}${clientRoute}?token${jwtToken}形式生成邮件里的深链接。如果生产环境该变量未指向公网域名用户收到的邮件链接将无法访问。WebSocket 来源校验waspc/data/Generator/templates/sdk/wasp/server/webSocket/initialization.ts 将config.frontendUrl作为允许的origin保证只有前端页面能建立实时连接。端口错误提示页waspc/data/Generator/templates/server/src/views/wrong-port.ts 会在开发者访问错端口时渲染一个指向frontendUrl的引导页。这些内部用法印证了文档对生产配置的强调frontendUrl必须是“服务端看来能到达前端的地址”。3. 客户端配置对象config.apiUrl客户端配置对象client configuration object包含字段apiUrlapiUrl: String—— 通过环境变量REACT_APP_API_URL设置表示服务端后端的 URL。开发阶段运行wasp start时由 Wasp自动设置为本地服务端地址生产阶段应包含用户浏览器视角下的服务端 URL同样考虑 DNS 与代理。访问方式import { config } from wasp/client console.log(config.apiUrl)3.1 源码级实现apiUrl与客户端 env 的嵌入时机对应模板 waspc/data/Generator/templates/sdk/wasp/client/config.tsconst apiUrl stripTrailingSlash(env[REACT_APP_API_URL]) // PUBLIC API export type ClientConfig { apiUrl: string, } // PUBLIC API export const config: ClientConfig { apiUrl, }其中REACT_APP_API_URL作为客户端侧的服务端 URL 变量名在部署工具中同样被显式引用见 waspc/data/packages/deploy/src/common/clientApp.tsconst serverUrlEnvVarName REACT_APP_API_URL。从源码结构看客户端配置的关键特性是它是构建期固化的。因为客户端生产环境只是静态文件REACT_APP_API_URL会在构建 client 时被替换并嵌入产物这与 Vite 对import.meta.env的构建期替换机制一致部署后再到托管平台改环境变量是无效的。这与服务端“运行时读取process.env”形成鲜明对比是部署配置时必须区分的一点。3.2apiUrl在框架内部的真实用途RPC 客户端请求前缀waspc/data/Generator/templates/sdk/wasp/api/index.ts 中 fetch 客户端以prefix: config.apiUrl作为所有 action/query 请求的 URL 前缀认证表单的登录/注册端点waspc/data/Generator/templates/sdk/wasp/auth/helpers/_Provider.tsx 用${config.apiUrl}/api/auth/signin等构造登录、注册、OAuth 登录入口如 LoginSignupForm.tsx 中的 Google/GitHub/Slack 登录 URLWebSocket 实时连接地址waspc/data/Generator/templates/sdk/wasp/client/webSocket/WebSocketProvider.tsx 以config.apiUrl为基础建立实时通道。4. 两个 URL 的关系与部署实践把前后两个配置对象放在一起看Wasp 的 URL 模型是一个双向指针配置项所在进程环境变量视角开发期config.frontendUrlserverWASP_WEB_CLIENT_URL服务端看到的客户端地址wasp start自动设置config.apiUrlclientREACT_APP_API_URL浏览器看到的服务端地址wasp start自动设置实践要点结合 v0.14 文档与仓库证据开发期零配置wasp start会自动填充上述变量前后端本地互通。生产期两侧都要显式配置客户端构建时必须把REACT_APP_API_URL传给构建命令客户端变量在构建期嵌入托管平台上的运行期变量对静态文件无效完整构建方式见手动部署文档服务端运行环境如 Fly 等平台的 secrets必须设置WASP_WEB_CLIENT_URL为公网前端域名。该变量同时决定生产 CORS 白名单漏配即全站 API 请求被浏览器拦截。开发期环境变量的定义方式客户端变量放.env.client必须带REACT_APP_前缀服务端变量放.env.server可存密钥详见环境变量文档。5. 版本适用性说明本文以 v0.14 文档为准需特别注意版本演进对 URL 配置契约的影响依据 waspc/ChangeLog.md早期版本中REACT_APP_API_URL曾是部署时指定自定义服务端 URL 的推荐方式后来 Wasp 改为由wasp build的--custom-server-url等 CLI 选项管理REACT_APP_API_URL在构建生产客户端时成为必填项不再允许缺省以避免“客户端连不上服务端”的静默失败更新版本中 Wasp 直接在开发期托管应用 URL自行设置WASP_SERVER_URL、WASP_WEB_CLIENT_URL、REACT_APP_API_URL会直接报错。因此若你在较新版本的 Wasp 项目中遇到 URL 配置问题应以对应版本的 ChangeLog 与部署文档为准但在理解配置对象语义frontendUrl/apiUrl的双向指针模型、CORS 派生、构建期嵌入方面本文结论对所有版本仍然成立。6. 小结Wasp 应用 React 客户端进程 Express 服务端进程二者分别通过环境变量配置并通过wasp/server的config.frontendUrl源WASP_WEB_CLIENT_URL与wasp/client的config.apiUrl源REACT_APP_API_URL在运行时相互感知开发期wasp start自动填充生产期需按“服务端视角配前端地址、浏览器视角配服务端地址”的语义显式设置从源码模板看frontendUrl还驱动生产 CORS 白名单、OAuth/邮件链接构造与 WebSocket 来源校验apiUrl驱动全部客户端 RPC 与认证端点拼接——配置这两个 URL 的正确性直接决定应用能否在公网正常工作。【免费下载链接】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），仅供参考