Wasp 前端Web Client生产构建指南从.wasp/build/web-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构建 Wasp 应用的前端web client是整个部署流程中的关键一环Wasp 会为你的应用生成一个独立的前端工程你需要在该工程内安装依赖、注入后端 API 地址并执行生产构建最终得到一组可直接交给任意静态托管平台的产物。本篇以 Wasp v0.12 版本的部署文档 _building-the-web-client.md 为核心结合仓库源码与测试用例完整讲解这条构建链路读完你可以独立完成由wasp build产物构建前端并交付部署的完整操作并理解每一步背后的实现原理。一、构建前端的前置条件先生成可部署代码构建 web client 的前提是 Wasp 已经完成了全栈代码生成。在项目根目录运行wasp build该命令会把整个应用的可部署代码生成到.wasp/build/目录下详见 manually.md 中的 Generating Deployable Code 一节。生成的目录中包含了三个关键组成部分后端服务server及其Dockerfile用于部署 API 服务前端工程web-app/即本篇要构建的对象数据库迁移等配套资源。:::caution 生产构建要求 PostgreSQL 默认情况下 Wasp 使用 SQLite 作为数据库但生产构建阶段将无法以 SQLite 完成wasp build。部署到生产环境前必须先将数据库迁移到 PostgreSQL。 :::二、进入前端工程目录.wasp/build/web-appwasp build完成后前端工程位于项目根目录下的.wasp/build/web-app。在终端中定位到该目录cd .wasp/build/web-app这是一个由 Wasp 生成器产出的完整前端工程包含自己的package.json、Vite 配置、以及由 Wasp SDK 生成的前端运行时代码位于node_modules/wasp或等价位置。从生成器源码看Wasp 为该目录单独定义了 Vite 构建产物的输出位置为工程内的build/子目录见 WebAppGenerator.hs 中viteBuildDirInWebAppDir [reldir|build|]。三、安装前端依赖npm install这一步为前端工程安装全部依赖包括 Wasp 运行时 SDK、React、Vite 等。安装完成后工程即可进行构建。从自动化部署的实现可以看出Wasp 官方部署工具在构建客户端时执行的正是同样的两步先npm install再调用 Vite 构建见 clientApp.ts 中buildClient的实现。也就是说本篇手动执行的命令与 Wasp 自动部署内部的行为是一致的。四、注入后端地址REACT_APP_API_URL构建命令的核心在于环境变量REACT_APP_API_URL它的值是你已经部署好的 Wasp 后端服务器 URLREACT_APP_API_URLurl_to_wasp_backend npm run build在 v0.12 的生成体系中npm run build实际上就是调用 Vite 执行生产构建。这一点在仓库的端到端测试 ViteBuildTest.hs 中得到印证——测试直接以npx vite build等价执行构建并前置注入REACT_APP_API_URL测试用例中使用http://localhost:3001作为示例值见 ViteBuildTest.hs。为什么这个变量必不可少REACT_APP_API_URL在 Wasp 生成器中有一个专门的命名常量serverUrlEnvVarName REACT_APP_API_URL见 Common.hs。它会被注入到 Wasp SDK 的客户端配置中const apiUrl stripTrailingSlash(env[REACT_APP_API_URL]) // ... export const config: ClientConfig { apiUrl, }以上摘自 SDK 模板 client/config.ts。前端所有与后端的通信——Queries、Actions、认证登录跳转等——都以config.apiUrl为前缀见 wasp/api/index.ts 中prefix: config.apiUrl以及 LoginSignupForm.tsx 中各 OAuth 跳转地址的拼接。因此如果这个值缺失或写错前端虽然能构建出来但运行时所有请求都会指向错误的后端甚至无法发起请求。值的格式校验SDK 对REACT_APP_API_URL有严格的运行时校验见 env/schema.ts它是必填项缺失时直接报错REACT_APP_API_URL is required它必须是合法的 URL否则报错REACT_APP_API_URL must be a valid URL无论开发模式还是生产模式import.meta.env.MODE production该变量都会被强制校验。五、执行生产构建与产物npm install REACT_APP_API_URLurl_to_wasp_backend npm run build这是原文档给出的完整命令。构建完成后静态产物输出在web-app工程内的build/目录即.wasp/build/web-app/build/里面是一组纯静态文件HTML、JS、CSS 与静态资源。由于前端最终只是一堆静态文件你可以把它部署到任何静态托管平台Netlify、任何 CDN 或对象存储均可无需专门的 Node.js 运行时。六、构建失败排查来自测试用例的验证清单仓库的 ViteBuildTest.hs 用一组端到端用例系统性地验证了构建边界这些用例恰好就是排查构建失败的最佳清单场景测试结果说明缺少REACT_APP_API_URL构建失败见 fail-on-missing-required-env-varsREACT_APP_API_URL是硬性必填注入内联环境变量构建成功见 success-with-required-env-vars必须以内联inline方式注入依赖.env.client文件构建产物中不含该值见 ignore-dotenv-client-file-in-build.env.client文件在构建时被忽略不要依赖 .env 文件注入该变量内联变量 .env文件共存内联变量生效见 inline-env-vars-work-with-env-file-presentsrc/中的类型错误构建失败见 fail-on-user-code-type-error用户源码类型错误会阻断 Vite 构建main.wasp.ts中的类型错误不影响构建见 ignore-wasp-ts-type-errorsWasp 声明文件类型错误被忽略自定义 Viteserver.port构建失败见 fail-on-user-defined-client-port生成的前端不允许用户自定义 dev server 端口其中最重要的一条实战教训是REACT_APP_API_URL必须通过命令行内联方式或 CI 环境变量注入不能写在.env.client文件里——Wasp 的构建流程特意忽略该文件以防错误配置进入生产产物。七、与后端环境变量的配套别忘了WASP_WEB_CLIENT_URL构建前端只是部署的一半。Wasp 后端在生产环境中还会读取一系列环境变量详见 manually.md 的 Environment Variables 一节其中与前端直接相关的是WASP_WEB_CLIENT_URL必填你计划部署前端的 URL例如https://app-name.netlify.app。服务器需要知道它才能正确配置 CORS同源策略响应头让浏览器允许前端跨域访问 API。JWT_SECRET使用 Wasp Auth 时必填至少 32 字符的随机字符串用于签名会话令牌。PORT后端 HTTP 监听端口默认3001。DATABASE_URL必填PostgreSQL 连接串。因此完整的部署链路是先部署后端并记录其 URL → 以该 URL 作为REACT_APP_API_URL构建前端 → 部署前端并记录其 URL → 再把这个前端 URL 回填到后端的WASP_WEB_CLIENT_URL使 CORS 配置与真实前端地址保持一致。八、把构建嵌入自动化部署流程如果你不想手动重复以上命令Wasp 提供了两种自动化方式Wasp CLI 一键部署wasp deploy fly launch app-name region会自动完成 server/client 的构建与部署见 cli.md。其内部实现正是调用了 clientApp.ts 中的buildClient在.wasp/build/web-app中执行npm install、注入REACT_APP_API_URL并执行vite build与手动流程完全等价。平台侧部署脚本在 Netlify、Railway 等静态托管平台把构建命令配置为上文手动命令的组合即可Railway 场景下还需将web-app/build/复制为dist/并配合静态服务器详见 manually.md 的 Railway 小节。无论走哪条路REACT_APP_API_URL的注入、npm install与生产构建这三个环节都是不可省略的。小结构建命令cd .wasp/build/web-app npm install REACT_APP_API_URL后端URL npm run build。产物位置.wasp/build/web-app/build/是纯静态文件可部署到任意静态托管。关键约束REACT_APP_API_URL必填、必须是合法 URL、必须内联注入.env.client会被忽略。配套要求前端 URL 需要回填到后端WASP_WEB_CLIENT_URL以正确配置 CORS。把这条构建链路与后端、数据库的部署串起来即可完成一个 Wasp 全栈应用从源码到生产环境的完整落地。【免费下载链接】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），仅供参考