Wasp 前端静态构建实战用 REACT_APP_API_URL 与 wasp build 产出可部署的 Web Client【免费下载链接】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 build即可生成后端Node.js 服务器、前端React 静态站点与数据库迁移脚本的可部署产物。本文聚焦构建 Web Client前端这一关键环节讲解如何进入.wasp/build/web-app目录、通过npm install REACT_APP_API_URL后端地址 npm run build产出静态文件并深入解析REACT_APP_API_URL在前端 SDK 中的校验与注入原理以及客户端环境变量在生产构建中的正确姿势。读完本文你将能够独立完成 Wasp 应用前端的构建、环境变量注入与静态托管部署。一、构建前的准备wasp build生成可部署代码构建 Web Client 之前必须先让 Wasp 生成整份可部署代码。在项目根目录运行wasp build该命令会在.wasp/build/目录下生成整个应用的可部署代码其中包含三个关键部分后端服务器代码.wasp/build/中的 Dockerfile 定义了服务器镜像的构建方式前端 Web 应用代码.wasp/build/web-app/即本文的主角数据库迁移由生成代码在部署时自动执行。:::caution 生产环境必须使用 PostgreSQL 如果项目仍在使用默认的 SQLite 数据库wasp build将无法成功构建。在部署到生产环境之前需要先在 schema.prisma 中将provider从sqlite改为postgresql删除旧迁移并重新执行wasp db migrate-dev。SQLite 仅适用于开发阶段。 :::二、进入前端构建目录构建 Web App 的第一步是定位到 Wasp 生成的前端工程目录cd .wasp/build/web-app该目录本质上是一个由 Wasp 生成器产出的独立 Vite React 工程。从源码结构看它会在构建时引用 Wasp SDK 中与客户端相关的模板代码例如 waspc/data/Generator/templates/sdk/wasp/client 下的config.ts、env/schema.ts等文件这些模板负责客户端的 API 地址解析与环境变量校验。三、核心构建命令注入后端地址并产出静态文件进入.wasp/build/web-app后执行npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你先前已经部署好的 Wasp 服务器地址例如https://app-name.fly.dev。为什么是REACT_APP_API_URLREACT_APP_API_URL是 Wasp 约定的、客户端定位后端 API 的固定环境变量名。Wasp 生成器在 waspc/src/Wasp/Generator/WebAppGenerator/Common.hs#L22 中将其硬编码为serverUrlEnvVarName REACT_APP_API_URL在生成的前端 SDK 中客户端会从该环境变量读取 API 地址并去除尾部斜杠见 waspc/data/Generator/templates/sdk/wasp/client/config.tsconst apiUrl stripTrailingSlash(env[REACT_APP_API_URL])也就是说前端所有的 Query/ActionRPC 调用最终都会指向这个地址。若该变量缺失或不是合法 URL构建产物在运行时就会报错——Wasp SDK 使用 Zod 对客户端环境变量做 schema 校验见 waspc/data/Generator/templates/sdk/wasp/client/env/schema.tsconst serverUrlSchema z.string({ error: REACT_APP_API_URL is required, }) .pipe( z.url({ error: REACT_APP_API_URL must be a valid URL, }) )因此在构建时传入合法、完整的 URL含https://协议前缀是硬性要求。构建产物在哪里执行成功后前端静态文件会输出到.wasp/build/web-app/build/目录。这一目录就是可以部署到任意静态托管平台Netlify、Cloudflare、Fly.io 静态服务等的内容。由于产出的是纯静态文件托管端无需运行 Node.js直接托管目录内容即可。四、客户端环境变量REACT_APP_ 前缀与生产注入Wasp 的客户端环境变量遵循REACT_APP_前缀约定详见 项目环境变量文档。这一点在 Wasp 生成的 Vite 配置中也有印证——envPrefix被设置为REACT_APP_见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts#L21envPrefix: REACT_APP_,只有以REACT_APP_开头的变量才会被 Vite 注入到客户端代码中供import.meta.env.REACT_APP_XXX读取。开发环境 vs 生产环境开发环境wasp start推荐在项目根目录的.env.client文件中定义REACT_APP_变量。生成器中的 Vite 插件只有在serve开发命令下才加载 dotenv 文件见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/envFile.ts#L25loadDotEnvFile: env.command serve,生产构建.env.client会被忽略。所有客户端环境变量必须以命令行前缀的方式直接传给npm run buildREACT_APP_API_URLhttps://your-backend REACT_APP_SOME_VARsomevalue npm run build这是因为这些变量会被嵌入到静态产物中成为公开可见的代码内容所以切勿把密钥如 API Secret放进客户端变量——密钥应作为服务端环境变量提供给后端。:::caution 别忘了你自定义的客户端变量 如果你在项目中额外定义了其他客户端环境变量比如REACT_APP_ANOTHER_VAR请在构建 Web Client 时把它们一并加到上面的命令中否则这些变量会缺失客户端读取到的将是undefined。 :::为什么不能在托管平台设置客户端变量Web Client 构建完成后只是一堆静态文件运行时不再有环境变量的概念。因此即便你在托管平台如 Fly.io、Netlify上为客户端设置了环境变量它们也不会生效——客户端变量必须在构建时刻注入。这也是 Wasp 文档反复强调每次构建都要重新传入客户端环境变量的根本原因。五、配套的后端环境变量确保前后端联通前端构建完成后请确认后端服务器已配置以下环境变量详见 手动部署指南环境变量必填作用DATABASE_URL是PostgreSQL 数据库连接串如postgresql://mydbuser:mypasslocalhost:5432/nameofmydbWASP_WEB_CLIENT_URL是前端部署后的访问地址如https://app-name.netlify.app服务器据此配置 CORS 同源策略WASP_SERVER_URL是服务器自身地址如https://app-name.fly.dev用于 OAuth 登录Google/GitHub时的重定向JWT_SECRET使用 Wasp Auth 时必填随机字符串长度至少 32 字符用于签发会话令牌PORT否服务器监听端口默认3001前后端联通的完整链路是前端在构建时通过REACT_APP_API_URL记住后端地址后端在运行时通过WASP_WEB_CLIENT_URL放行前端的跨域请求二者缺一不可。六、部署静态产物与重新部署要点部署到静态托管将.wasp/build/web-app/build/目录的内容部署到任意静态托管服务即可。以 Netlify 为例# 先完成上述前端构建 netlify deploy # 首次部署草稿预览 netlify deploy --prod # 发布到生产部署完成后将得到的前端地址如https://app-name.netlify.app设置为后端服务器的WASP_WEB_CLIENT_URL。重新构建时的注意事项每次修改代码后重新运行wasp buildWasp 都会清空并重建.wasp/build/目录。这意味着之前生成的.wasp/build/web-app/build/会被删除如果你在.wasp/build/内放置过自定义的部署配置文件如 Fly.io 的fly.toml需要将其复制到版本控制的目录如项目根目录中留存部署时通过--config指定路径。因此合理的部署流程是wasp build→ 进入.wasp/build/web-app→ 注入环境变量构建前端 → 将build/内容发布到静态托管。七、进阶用 Wasp CLI 一键部署如果你不想手动执行上述构建与部署步骤Wasp CLI 提供了自动化能力。对于 Fly.io一条命令即可完成服务器、客户端与数据库的部署wasp deploy fly launch my-wasp-app mia其内部等价于依次执行setup、create-db、deploy。需要传入客户端环境变量时在命令前以 shell 前缀方式给出REACT_APP_ANOTHER_VARsomevalue wasp deploy fly launch my-wasp-app mia注意客户端环境变量在每次执行wasp deploy fly deploy更新线上应用时都必须重新传入否则会因未注入而缺失。总结构建 Wasp Web Client 的核心链路可以概括为三步wasp build生成前端工程 → 在.wasp/build/web-app中通过REACT_APP_API_URL注入后端地址并执行npm run build→ 将build/目录托管到任意静态平台同时确保后端配置好WASP_WEB_CLIENT_URL、DATABASE_URL等运行时变量。理解REACT_APP_前缀、构建时注入、静态产物无环境变量这三个关键点就能避免前端部署中最常见的客户端连不上后端类问题。【免费下载链接】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），仅供参考 
长河君 · 2026/9/14 15:54:45 · 阅读 1.2k Wasp 前端静态构建实战：用 REACT_APP_API_URL 与 wasp build 产出可部署的 Web Client
Wasp 前端静态构建实战用 REACT_APP_API_URL 与 wasp build 产出可部署的 Web Client【免费下载链接】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 build即可生成后端Node.js 服务器、前端React 静态站点与数据库迁移脚本的可部署产物。本文聚焦构建 Web Client前端这一关键环节讲解如何进入.wasp/build/web-app目录、通过npm install REACT_APP_API_URL后端地址 npm run build产出静态文件并深入解析REACT_APP_API_URL在前端 SDK 中的校验与注入原理以及客户端环境变量在生产构建中的正确姿势。读完本文你将能够独立完成 Wasp 应用前端的构建、环境变量注入与静态托管部署。一、构建前的准备wasp build生成可部署代码构建 Web Client 之前必须先让 Wasp 生成整份可部署代码。在项目根目录运行wasp build该命令会在.wasp/build/目录下生成整个应用的可部署代码其中包含三个关键部分后端服务器代码.wasp/build/中的 Dockerfile 定义了服务器镜像的构建方式前端 Web 应用代码.wasp/build/web-app/即本文的主角数据库迁移由生成代码在部署时自动执行。:::caution 生产环境必须使用 PostgreSQL 如果项目仍在使用默认的 SQLite 数据库wasp build将无法成功构建。在部署到生产环境之前需要先在 schema.prisma 中将provider从sqlite改为postgresql删除旧迁移并重新执行wasp db migrate-dev。SQLite 仅适用于开发阶段。 :::二、进入前端构建目录构建 Web App 的第一步是定位到 Wasp 生成的前端工程目录cd .wasp/build/web-app该目录本质上是一个由 Wasp 生成器产出的独立 Vite React 工程。从源码结构看它会在构建时引用 Wasp SDK 中与客户端相关的模板代码例如 waspc/data/Generator/templates/sdk/wasp/client 下的config.ts、env/schema.ts等文件这些模板负责客户端的 API 地址解析与环境变量校验。三、核心构建命令注入后端地址并产出静态文件进入.wasp/build/web-app后执行npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你先前已经部署好的 Wasp 服务器地址例如https://app-name.fly.dev。为什么是REACT_APP_API_URLREACT_APP_API_URL是 Wasp 约定的、客户端定位后端 API 的固定环境变量名。Wasp 生成器在 waspc/src/Wasp/Generator/WebAppGenerator/Common.hs#L22 中将其硬编码为serverUrlEnvVarName REACT_APP_API_URL在生成的前端 SDK 中客户端会从该环境变量读取 API 地址并去除尾部斜杠见 waspc/data/Generator/templates/sdk/wasp/client/config.tsconst apiUrl stripTrailingSlash(env[REACT_APP_API_URL])也就是说前端所有的 Query/ActionRPC 调用最终都会指向这个地址。若该变量缺失或不是合法 URL构建产物在运行时就会报错——Wasp SDK 使用 Zod 对客户端环境变量做 schema 校验见 waspc/data/Generator/templates/sdk/wasp/client/env/schema.tsconst serverUrlSchema z.string({ error: REACT_APP_API_URL is required, }) .pipe( z.url({ error: REACT_APP_API_URL must be a valid URL, }) )因此在构建时传入合法、完整的 URL含https://协议前缀是硬性要求。构建产物在哪里执行成功后前端静态文件会输出到.wasp/build/web-app/build/目录。这一目录就是可以部署到任意静态托管平台Netlify、Cloudflare、Fly.io 静态服务等的内容。由于产出的是纯静态文件托管端无需运行 Node.js直接托管目录内容即可。四、客户端环境变量REACT_APP_ 前缀与生产注入Wasp 的客户端环境变量遵循REACT_APP_前缀约定详见 项目环境变量文档。这一点在 Wasp 生成的 Vite 配置中也有印证——envPrefix被设置为REACT_APP_见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts#L21envPrefix: REACT_APP_,只有以REACT_APP_开头的变量才会被 Vite 注入到客户端代码中供import.meta.env.REACT_APP_XXX读取。开发环境 vs 生产环境开发环境wasp start推荐在项目根目录的.env.client文件中定义REACT_APP_变量。生成器中的 Vite 插件只有在serve开发命令下才加载 dotenv 文件见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/envFile.ts#L25loadDotEnvFile: env.command serve,生产构建.env.client会被忽略。所有客户端环境变量必须以命令行前缀的方式直接传给npm run buildREACT_APP_API_URLhttps://your-backend REACT_APP_SOME_VARsomevalue npm run build这是因为这些变量会被嵌入到静态产物中成为公开可见的代码内容所以切勿把密钥如 API Secret放进客户端变量——密钥应作为服务端环境变量提供给后端。:::caution 别忘了你自定义的客户端变量 如果你在项目中额外定义了其他客户端环境变量比如REACT_APP_ANOTHER_VAR请在构建 Web Client 时把它们一并加到上面的命令中否则这些变量会缺失客户端读取到的将是undefined。 :::为什么不能在托管平台设置客户端变量Web Client 构建完成后只是一堆静态文件运行时不再有环境变量的概念。因此即便你在托管平台如 Fly.io、Netlify上为客户端设置了环境变量它们也不会生效——客户端变量必须在构建时刻注入。这也是 Wasp 文档反复强调每次构建都要重新传入客户端环境变量的根本原因。五、配套的后端环境变量确保前后端联通前端构建完成后请确认后端服务器已配置以下环境变量详见 手动部署指南环境变量必填作用DATABASE_URL是PostgreSQL 数据库连接串如postgresql://mydbuser:mypasslocalhost:5432/nameofmydbWASP_WEB_CLIENT_URL是前端部署后的访问地址如https://app-name.netlify.app服务器据此配置 CORS 同源策略WASP_SERVER_URL是服务器自身地址如https://app-name.fly.dev用于 OAuth 登录Google/GitHub时的重定向JWT_SECRET使用 Wasp Auth 时必填随机字符串长度至少 32 字符用于签发会话令牌PORT否服务器监听端口默认3001前后端联通的完整链路是前端在构建时通过REACT_APP_API_URL记住后端地址后端在运行时通过WASP_WEB_CLIENT_URL放行前端的跨域请求二者缺一不可。六、部署静态产物与重新部署要点部署到静态托管将.wasp/build/web-app/build/目录的内容部署到任意静态托管服务即可。以 Netlify 为例# 先完成上述前端构建 netlify deploy # 首次部署草稿预览 netlify deploy --prod # 发布到生产部署完成后将得到的前端地址如https://app-name.netlify.app设置为后端服务器的WASP_WEB_CLIENT_URL。重新构建时的注意事项每次修改代码后重新运行wasp buildWasp 都会清空并重建.wasp/build/目录。这意味着之前生成的.wasp/build/web-app/build/会被删除如果你在.wasp/build/内放置过自定义的部署配置文件如 Fly.io 的fly.toml需要将其复制到版本控制的目录如项目根目录中留存部署时通过--config指定路径。因此合理的部署流程是wasp build→ 进入.wasp/build/web-app→ 注入环境变量构建前端 → 将build/内容发布到静态托管。七、进阶用 Wasp CLI 一键部署如果你不想手动执行上述构建与部署步骤Wasp CLI 提供了自动化能力。对于 Fly.io一条命令即可完成服务器、客户端与数据库的部署wasp deploy fly launch my-wasp-app mia其内部等价于依次执行setup、create-db、deploy。需要传入客户端环境变量时在命令前以 shell 前缀方式给出REACT_APP_ANOTHER_VARsomevalue wasp deploy fly launch my-wasp-app mia注意客户端环境变量在每次执行wasp deploy fly deploy更新线上应用时都必须重新传入否则会因未注入而缺失。总结构建 Wasp Web Client 的核心链路可以概括为三步wasp build生成前端工程 → 在.wasp/build/web-app中通过REACT_APP_API_URL注入后端地址并执行npm run build→ 将build/目录托管到任意静态平台同时确保后端配置好WASP_WEB_CLIENT_URL、DATABASE_URL等运行时变量。理解REACT_APP_前缀、构建时注入、静态产物无环境变量这三个关键点就能避免前端部署中最常见的客户端连不上后端类问题。【免费下载链接】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），仅供参考