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 的环境； - 数据库（Database）：Wasp 生产环境默认使用 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_URL=https://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_URL=https://myapp.com WASP_SERVER_URL=https://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_URL：
wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URL=https://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.com（TTL 可设 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 dfw），Wasp 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_URL | URL | 必填 | 客户端用它作为服务端 URL |
WASP_WEB_CLIENT_URL | URL | 必填 | 服务端用它作为客户端 URL（邮件链接、CORS 等） |
WASP_SERVER_URL | URL | 必填 | 服务端用它作为自身 URL（OAuth 重定向等） |
DATABASE_URL | String | 必填 | PostgreSQL 数据库连接串 |
PORT | Integer | 必填 | 服务端监听端口 |
JWT_SECRET | String | 必填 | 至少 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 文档，生产上线前建议逐项核对：
- 客户端域名：DNS
A/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），仅供参考
