Wasp 生产部署补充指南自定义域名、CDN 防护与生产就绪性【免费下载链接】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 官方部署文档中Extras生产部署补充主题的完整展开版配套仓库为 wasp 开源项目GitHub_Trending/wa/wasp。文章聚焦三个实战问题如何在客户端与服务端分别接入自定义域名并正确配置环境变量、如何用 CDN 与 DDoS 防护提升线上应用的性能与安全性以及 Wasp 生成的客户端 服务端 数据库三段式应用在生产环境中的技术底座与就绪边界。读完本文你将掌握从 DNS 记录到WASP_WEB_CLIENT_URL/WASP_SERVER_URL配置的完整自定义域名接入流程并能在 Fly.io / Railway 等平台上独立完成配置排错。一、先回顾Wasp 应用的生产形态是三段式在深入 Extras 之前需要先建立正确的部署心智模型。正如 部署引言 所述一个Wasp 应用实际由三个相互独立的构件组成客户端应用Client app基于 React 构建的单页应用SPA是用户通过浏览器直接访问的部分通常由静态文件服务器或 CDN如 Cloudflare、Netlify托管服务端应用Server app基于 Node.js 上的 Express 框架构建的后端负责处理客户端请求、与数据库交互并返回响应自带可直接打包的Dockerfile可部署到任何支持 Docker 的环境数据库DatabaseWasp 生产环境默认使用 PostgreSQL可以自托管也可以使用云数据库服务。关键在于客户端与服务端是两个通过 HTTP 通信的独立应用因此可以部署在同一台服务器上也可以分别部署——自定义域名、CDN 加速等额外主题正是建立在这个三段式架构之上。二、自定义域名设置客户端是必选项服务端是可选项生产环境最常见的诉求是让用户通过自己的域名访问应用。在 Extras 文档 中Wasp 明确区分了两个设置目标客户端域名必做这是用户从浏览器访问的地址是自定义域名的核心诉求服务端域名可选设置服务端域名可以隐藏服务器细节如 IP 地址或自动生成的域名对用户不可见但能提升专业性并降低暴露面。无论客户端还是服务端接入自定义域名通常都是两步走配置 DNS 记录在域名托管商的 DNS 设置中添加A记录指向应用的 IPv4 地址通常还会设置AAAA记录指向 IPv6 地址。部分托管商要求改用CNAME记录而非A/AAAA记录具体取决于你的托管平台配置环境变量设置环境变量让 Wasp 正确配置应用例如让 CORS 正常工作。如果你使用 Wasp CLI 的wasp deploy命令部署请直接参考 Fly.io 自定义域名指南 或 Railway 自定义域名指南它们提供了对应平台的逐步操作。三、域名相关的环境变量配置环境变量是把域名告诉 Wasp的桥梁。以下是客户端与服务端各自必须设置的变量完整清单见 项目环境变量文档3.1 客户端域名变量在构建客户端时详见 部署环境变量客户端将REACT_APP_API_URL设置为指向你的服务端域名REACT_APP_API_URLhttps://api.myapp.comREACT_APP_API_URL是 Wasp 预定义、生产环境必填的客户端环境变量客户端用它作为服务端 URL开发环境下由 Wasp 自动设置。更多客户端配置可查阅 env vars 文档的客户端通用配置小节。需要特别强调的是客户端环境变量是在构建过程中注入到客户端 JS 代码里的任何人查看网页源码都能读到因此绝不能在其中存放密钥如 API Secret Key应放入服务端环境变量。3.2 服务端域名变量对于服务端需要配置两个变量详见 部署环境变量服务端WASP_WEB_CLIENT_URL客户端应用的域名WASP_SERVER_URL服务端应用的域名。WASP_WEB_CLIENT_URLhttps://myapp.com WASP_SERVER_URLhttps://server.myapp.com这两个变量在 Wasp 生成的服务端代码中是硬编码的内置环境变量名。在 waspc 源码 中可以确认它们的定义clientUrlEnvVarName WASP_WEB_CLIENT_URL serverUrlEnvVarName WASP_SERVER_URL这两个变量的作用差异可以从 项目环境变量文档 中读出WASP_WEB_CLIENT_URL服务端在各种功能中把它当作你的客户端 URL 使用例如在邮件中拼接指向你应用的链接邮件验证、密码重置等场景WASP_SERVER_URL服务端用它作为自身 URL例如使用 Google、GitHub 等 OAuth 提供商登录时重定向用户回应用。注意这两个变量与DATABASE_URL、PORT、JWT_SECRET一样都是Wasp 定义、生产环境必填的服务端环境变量。开发环境下 Wasp 会自动设置可通过wasp start --client-port/wasp start --server-port调整但生产环境必须显式配置缺失会导致服务端启动失败。3.3 自定义域名与 CORS 的关系为什么必须配置这些变量一个重要原因是CORS跨域资源共享。客户端与服务端分别位于不同域名如myapp.com与api.myapp.com时浏览器会发起跨域请求服务端必须基于WASP_WEB_CLIENT_URL生成允许跨域的响应头。若该变量与用户实际访问的客户端域名不一致就会出现 CORS 报错、请求被浏览器拦截。这也解释了 Fly.io / Railway 文档中的一条操作惯例在设置自定义域名后必须把新客户端 URL 同步为服务端应用上的WASP_WEB_CLIENT_URL环境变量。四、平台实战Fly.io 与 Railway 上的自定义域名4.1 Fly.io三步接入自定义域名在 Fly.io 部署文档 中设置自定义域名的完整流程如下第一步为客户端应用添加证书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_URLwasp 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指向根域名mycoolapp.comTTL 可设 3600。CNAME 记录Canonical name将www子域名声明为根域名的别名。完成后两个地址均可访问。⚠️CORS 警告同时使用www与non-www两个域名时必须更新服务端 CORS 配置以同时允许两个域名的请求否则两个域名同时访问会出现跨域问题。4.2 Railway在控制台完成自定义域名Railway 部署文档 的自定义域名流程同样分三步但主要在 Railway 控制台操作为客户端服务添加域名进入 Railway 控制台 → 选择项目 → 点击客户端服务如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访问。4.3 服务端使用自定义域名--custom-server-url选项如果你希望客户端连接到不同的服务端 URL例如服务端也使用了自定义域名Wasp CLI 提供了--custom-server-url选项见 wasp-deploy 公共片段wasp deploy fly launch my-wasp-app dfw --custom-server-url https://api.myapp.com wasp deploy railway launch my-wasp-app --custom-server-url https://api.myapp.com这正对应原文档中的服务端域名配置REACT_APP_API_URL指向https://api.myapp.com服务端的WASP_SERVER_URL也指向该地址从而隐藏自动生成的服务器域名。4.4launch命令帮你自动设置哪些变量如果你使用 Wasp CLI 的launch命令如wasp deploy fly launch my-wasp-app dfwWasp CLI 会自动把三段式应用连接起来并设置服务端必需的环境变量见 launch 命令环境变量说明WASP_WEB_CLIENT_URL与WASP_SERVER_URL连接客户端与服务端所必需DATABASE_URL连接服务端与数据库所必需JWT_SECRET认证功能所必需。也就是说通用配置由 CLI 代劳但OAuth 密钥、邮件服务密钥等其余环境变量仍需你自行设置——可以通过--server-secret选项在launch/setup时传入或部署后在平台上用secrets set/ 控制台 Variables 补充。五、生产环境环境变量速查表以下变量在自定义域名场景下必须正确配置均来自 项目环境变量文档 的 Wasp 预定义清单变量类型生产环境用途REACT_APP_API_URLURL必填客户端用它作为服务端 URLWASP_WEB_CLIENT_URLURL必填服务端用它作为客户端 URL邮件链接、CORS 等WASP_SERVER_URLURL必填服务端用它作为自身 URLOAuth 重定向等DATABASE_URLString必填PostgreSQL 数据库连接串PORTInteger必填服务端监听端口JWT_SECRETString必填至少 32 字符的随机串用于生成安全令牌开发环境默认DEVJWTSECRET关于环境变量的更多细节.env.client/.env.server开发环境用法、Zod 自定义校验、JSON 环境变量转义等请参考 项目环境变量文档 与 部署环境变量文档。一个关键提醒生产部署时.env.client与.env.server都会被忽略客户端变量必须在构建命令前以 shell 前缀传入如REACT_APP_API_URL... npx vite build服务端变量则通过托管平台机制设置在托管平台给静态客户端文件设置客户端变量是无效的因为构建后客户端只是一堆静态文件。六、CDN 与 DDoS 防护建议自定义域名上线后生产环境还需要考虑性能与安全加固。Wasp 官方在 Extras 文档 中给出了两条明确建议6.1 用 CDN 加速静态资源内容分发网络CDN是全球分布的服务器网络专门缓存图片、CSS、JavaScript 等静态资源。将 CDN 置于客户端之前可以帮助缓存静态资源并让全球用户就近获取用户请求文件时CDN 从离用户最近的服务器提供服务显著改善加载时间。考虑到 Wasp 客户端本身就是一个 React SPA静态文件集合CDN 加速的收益尤为直接。6.2 用 DDoS 防护抵御流量攻击分布式拒绝服务DDoS攻击是 Web 应用的常见威胁攻击者向服务器发送海量流量使其过载而无法为合法用户服务。建议为客户端和服务端都启用 DDoS 防护服务。6.3 服务商选择Wasp 官方推荐使用Cloudflare同时承担 CDN 与 DDoS 防护设置简单且免费套餐对大多数中小型应用已经足够。此外也可考虑 Fastly、Bunny 和 Amazon CloudFront 等 CDN 提供商。具体选型可结合预算、地域覆盖与已有基础设施例如你的 DNS 是否已托管在某个平台决定。七、Wasp 应用生产就绪吗最后一个高频问题是Wasp 生成的应用能否直接上生产回答这个问题仍要回到三段式架构服务端基于 Node.js 与久经考验的Express.js框架数据库使用强大可靠的PostgreSQL客户端基于广泛使用且维护良好的React Vite。每一层单独来看都是生产级别的成熟技术Wasp 所做的是让它们开箱即用地连接在一起一键命令、自动环境变量、内置 CORS 与认证等。不过文档也坦诚地指出Wasp 仍被视为 beta 软件因此可能存在一些粗糙的边缘场景。这并不意味着不能上生产——仓库中的 ask-the-documents、waspello、waspleau 等示例项目均提供了完整的部署配置fly-client.toml、fly-server.toml可供你对照实际部署形态但对于生产环境建议为关键路径做好充分的集成测试与监控并关注框架更新。八、总结上线前的检查清单结合 部署引言 与 Extras 文档生产上线前建议逐项核对客户端域名DNSA/AAAA或CNAME记录已生效证书签发完成服务端域名可选如需隐藏服务器细节为服务端配置自定义域名并用--custom-server-url或环境变量让客户端知晓环境变量REACT_APP_API_URL、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、DATABASE_URL、PORT、JWT_SECRET均已正确设置域名变更后务必同步更新WASP_WEB_CLIENT_URL以保持 CORS 正常性能与安全客户端前置 CDN 缓存静态资源客户端与服务端均启用 DDoS 防护认知边界认清三段式架构React/Vite Node/Express PostgreSQL各自独立部署的特性理解 Wasp 仍处 beta 阶段为边缘场景留出测试余量。【免费下载链接】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），仅供参考