Wasp 前端静态构建指南手动构建 Web 客户端并部署到任意静态托管平台【免费下载链接】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导读在 Wasp0.16 版本中部署全栈应用时后端Node.js 服务器与前端Web 客户端是两条独立的流水线wasp build先生成可部署的工程代码随后你需要在.wasp/build/web-app目录下手动构建前端静态文件并通过REACT_APP_API_URL把已部署的后端地址注入到客户端代码中。本文将基于 Wasp 仓库中 version-0.16 部署文档 的完整流程结合仓库源码与配套文档讲解手动构建 Web 客户端的完整步骤、客户端环境变量的注入原理、构建产物的去向以及如何将产物部署到 Netlify、Cloudflare 等静态托管平台。读完本文你将掌握在不依赖 Wasp CLI 一键部署的情况下手工完成前端构建与部署的完整实战能力。前置条件先完成wasp build在手动构建 Web 客户端之前必须先保证整个应用已经生成了可部署的代码。在 Wasp 项目根目录执行wasp build该命令会在.wasp/build/目录下生成全栈的可部署产物其中包括server/Node.js 服务器代码配合生成的 Dockerfile 部署到任意支持容器的平台web-app/Web 客户端工程也就是本文要手动构建的对象db/数据库相关迁移与配置。在 PaaS 部署文档 中整个部署流程被概括为四步生成可部署代码、部署 API 服务器后端、部署 Web 客户端前端、部署并持续运行 PostgreSQL 数据库。手动构建客户端对应其中的第三步。⚠️注意如果项目仍在使用默认的 SQLite 数据库wasp build将无法成功构建生产产物。部署到生产环境前必须先将数据库切换为 PostgreSQL具体步骤见 数据模型文档 中的 Migrating from SQLite to PostgreSQL。从源码层面看.wasp/build/web-app目录由 Wasp 生成器在 WebAppGenerator.hs 中定义webAppRootDirInGeneratedAppDir [reldir|web-app|]明确了该目录在生成产物中的位置而viteBuildDirInWebAppDir [reldir|build|]则定义了后续 Vite 构建输出的静态文件目录为web-app/build。这段源码还注释说明We require theweb-appdir to be generated for deployment purposes——即该目录专门为部署而生成部署工具链需要在用户项目目录之外有一个可以放置静态服务器 Dockerfile 或 Staticfile 的地方。手动构建 Web 客户端三步命令进入.wasp/build/web-app目录cd .wasp/build/web-app然后执行npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中npm install安装客户端工程的依赖首次构建或node_modules被清除时必需REACT_APP_API_URLurl_to_wasp_backend后端地址url_to_wasp_backend必须替换为你已经部署好的 Wasp 服务器的实际 URL例如https://my-app.fly.devnpm run build调用 Vite 执行生产构建产出静态文件。构建完成后产物位于.wasp/build/web-app/build/目录下它是一组纯静态文件HTML、JS、CSS 与静态资源可以直接部署到任意静态托管平台如 Netlify、Cloudflare Pages 等部署方式就是把.wasp/build/web-app/build/目录的内容托管出去。重点提醒来自原文档的 caution如果你在项目中还定义了其他客户端侧环境变量开发模式下写在.env.client中在构建时也必须把它们一并追加到上面的命令里。例如npm install REACT_APP_API_URLurl_to_wasp_backend REACT_APP_SOME_OTHER_VAR_NAMEsomeothervalue npm run build否则这些客户端变量在生产构建产物中不会存在依赖它们的代码会在运行时拿到未定义值。为什么客户端环境变量必须写在构建命令里这与客户端环境变量在 Wasp 中的工作方式直接相关详见 部署环境变量文档开发阶段你可以在项目根目录创建.env.client和.env.server两个文件来分别管理客户端与服务端变量但部署阶段这两个文件都会被忽略必须改用其他方式提供变量对客户端而言变量必须在构建命令中以内联方式传入。它们会被注入到客户端 JS 代码里因此是公开、任何人可读的——绝对不要在客户端变量中存放密钥如 API 密钥密钥应放入服务端环境变量与服务器环境变量不同不能也不应该通过在托管平台上设置环境变量来为客户端代码提供变量——因为构建完成后的客户端只是一堆静态文件运行期读取不到任何宿主环境变量。其底层原理文档中专门有一段 How it works构建过程中Wasp 会把客户端代码里的import.meta.env.REACT_APP_SOME_VAR_NAME全部替换为你在命令中提供的实际值。替换发生在构建阶段因此值是直接注入进静态产物文件中的——这正是 Vite 在生产构建中对import.meta.env的标准替换机制Vite 文档中的 Production Replacement。在代码层面对应的产物位置也有明确佐证Wasp 客户端工具链基于 Vite 构建生成器在 WebAppGenerator.hs 中定义了完整的产物路径链.wasp/build→web-app→build。这与你手动执行cd .wasp/build/web-app npm run build后看到的输出目录完全一致。在客户端代码中如何引用这些变量在生产构建中传入REACT_APP_API_URL等变量后客户端代码通过wasp/client暴露的env对象读取详见 项目环境变量文档import { env } from wasp/client // Wasp 内置定义的客户端变量 const apiUrl env.REACT_APP_API_URL // 用户自定义的客户端变量 const analyticsId env.REACT_APP_ANALYTICS_ID你也可以直接使用import.meta.env.REACT_APP_SOME_VAR_NAME但官方不推荐——因为import.meta.env未经校验缺失的变量可能引发运行时错误。更稳妥的做法是在 src/env.ts 中用 Zod 定义clientEnvValidationSchema通过wasp/env的defineEnvValidationSchema并在main.wasp的app声明中通过client.envValidationSchema注册让 Wasp 在验证import.meta.env时把内置 schema 与你自定义的 schema 合并执行。REACT_APP_API_URL的默认值与语义REACT_APP_API_URL是 Wasp 预置的客户端环境变量客户端用它作为访问后端服务器的 URL。在开发模式下它的默认值为http://localhost:3001即本地 Wasp 服务器默认监听地址因此在wasp start开发时通常无需显式配置而生产构建时必须显式传入已部署后端的地址否则客户端发起的 API 请求将指向错误位置前后端无法联通。结合部署场景的完整实践方式一PaaS 全流程中的客户端构建在 PaaS 部署文档 中_building-the-web-client.md这段内容被作为通用步骤嵌入到各平台的部署指南里。以 Railway 为例部署客户端的完整链路是# 1. 进入客户端工程目录 cd .wasp/build/web-app # 2. 用服务器域名作为 REACT_APP_API_URL 完成生产构建 npm install REACT_APP_API_URLurl_to_wasp_backend npm run build # 3. 链接到 Railway 项目配置静态托管 railway link cp -r build dist # 编写 Dockerfile基于 gostatic与 .dockerignore然后 railway up 部署以 Netlify 为例客户端专用静态托管# 同样先构建客户端 cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build # 使用 Netlify CLI 部署先试部署再发布到生产 npx netlify-cli deploy npx netlify-cli deploy --prod以 Cloudflare Pages 为例cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build npx wrangler pages deploy ./build --commit-dirtytrue --branchmain无论部署到哪个平台客户端上线后都别忘了把客户端 URL 设置到服务端环境变量WASP_WEB_CLIENT_URL中例如flyctl secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client否则服务端的邮件链接、OAuth 回调等功能将无法正确跳转回前端。方式二用 Wasp CLI 一键部署替代手工构建如果你不想手动执行上述三步可以直接使用 Wasp CLI 的部署命令。Wasp CLI 会替你完成服务器部署、客户端部署和数据库配置并支持一条命令重新部署更新应用。详见 Wasp CLI 部署文档。不过即使使用 CLI理解本文的手动构建流程仍然有价值——它揭示了 CLI 在背后执行的本质操作也有助于排查部署问题。客户端部署的额外注意点SPA 路由回退fallbackWasp 的客户端是一个单页应用SPA所有路由由客户端处理。因此静态托管平台必须把未知路径回退到index.html部署到 Netlify 时Wasp 默认会在.wasp/build/web-app/下生成netlify.tomlNetlify CLI 会自动读取它并配置好 URL 重定向到index.html。如果你改用其他方式如 CI 部署务必确保netlify.toml被平台拾取或手动配置重定向部署到 Cloudflare Pages 时平台会自动将所有路径重定向到index.html无需额外配置。每次wasp build之后都要重新构建客户端wasp build每次都会重建实际上会清空.wasp/build/目录因此.wasp/build/web-app及其中的构建产物都会被覆盖。任何涉及客户端的部署脚本如 PaaS 文档 中 Railway 的deploy_client.sh自动化脚本都需要在每次wasp build之后重新执行npm install REACT_APP_API_URL... npm run build。同样地如果直接把fly.toml等部署配置放在.wasp/build/下也会在重新构建时被清除——文档建议将其复制到版本管理目录如项目根目录并通过--config参数引用。常见问题排查症状原因与排查方向构建命令报错提示 SQLite项目仍在使用默认 SQLite 数据库需先按 数据模型文档 切换为 PostgreSQL 后再wasp build前端能打开但接口全部失败REACT_APP_API_URL未传入、传错或指向了未部署的后端确认值必须与已部署服务器的真实 URL 一致自定义客户端变量在生产端为undefined构建命令遗漏了该变量需与REACT_APP_API_URL一同以内联方式传入前端刷新出现 404静态托管平台未配置 SPA 路由回退到index.html参照上文 Netlify / Cloudflare 的说明处理邮件、OAuth 跳转指向错误地址服务端缺少或错误配置了WASP_WEB_CLIENT_URL需设置为已部署客户端 URL小结Wasp 的前端部署本质上是构建静态文件 静态托管两个环节wasp build生成客户端工程 → 在.wasp/build/web-app中执行npm install REACT_APP_API_URLurl_to_wasp_backend npm run build→ 把.wasp/build/web-app/build/的静态产物部署到任意静态托管平台。核心要点有三个REACT_APP_API_URL必须在构建命令中显式传入已部署后端地址其他客户端变量同样要在构建时内联注入它们会进入公开的静态产物严禁放密钥每次重新wasp build后都必须重做客户端构建与部署。掌握这条手动链路后你既可以用它把前端部署到任何你偏好的平台也能更深入地理解 Wasp CLI 一键部署背后的工作原理。【免费下载链接】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），仅供参考
Wasp 前端静态构建指南手动构建 Web 客户端并部署到任意静态托管平台【免费下载链接】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导读在 Wasp0.16 版本中部署全栈应用时后端Node.js 服务器与前端Web 客户端是两条独立的流水线wasp build先生成可部署的工程代码随后你需要在.wasp/build/web-app目录下手动构建前端静态文件并通过REACT_APP_API_URL把已部署的后端地址注入到客户端代码中。本文将基于 Wasp 仓库中 version-0.16 部署文档 的完整流程结合仓库源码与配套文档讲解手动构建 Web 客户端的完整步骤、客户端环境变量的注入原理、构建产物的去向以及如何将产物部署到 Netlify、Cloudflare 等静态托管平台。读完本文你将掌握在不依赖 Wasp CLI 一键部署的情况下手工完成前端构建与部署的完整实战能力。前置条件先完成wasp build在手动构建 Web 客户端之前必须先保证整个应用已经生成了可部署的代码。在 Wasp 项目根目录执行wasp build该命令会在.wasp/build/目录下生成全栈的可部署产物其中包括server/Node.js 服务器代码配合生成的 Dockerfile 部署到任意支持容器的平台web-app/Web 客户端工程也就是本文要手动构建的对象db/数据库相关迁移与配置。在 PaaS 部署文档 中整个部署流程被概括为四步生成可部署代码、部署 API 服务器后端、部署 Web 客户端前端、部署并持续运行 PostgreSQL 数据库。手动构建客户端对应其中的第三步。⚠️注意如果项目仍在使用默认的 SQLite 数据库wasp build将无法成功构建生产产物。部署到生产环境前必须先将数据库切换为 PostgreSQL具体步骤见 数据模型文档 中的 Migrating from SQLite to PostgreSQL。从源码层面看.wasp/build/web-app目录由 Wasp 生成器在 WebAppGenerator.hs 中定义webAppRootDirInGeneratedAppDir [reldir|web-app|]明确了该目录在生成产物中的位置而viteBuildDirInWebAppDir [reldir|build|]则定义了后续 Vite 构建输出的静态文件目录为web-app/build。这段源码还注释说明We require theweb-appdir to be generated for deployment purposes——即该目录专门为部署而生成部署工具链需要在用户项目目录之外有一个可以放置静态服务器 Dockerfile 或 Staticfile 的地方。手动构建 Web 客户端三步命令进入.wasp/build/web-app目录cd .wasp/build/web-app然后执行npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中npm install安装客户端工程的依赖首次构建或node_modules被清除时必需REACT_APP_API_URLurl_to_wasp_backend后端地址url_to_wasp_backend必须替换为你已经部署好的 Wasp 服务器的实际 URL例如https://my-app.fly.devnpm run build调用 Vite 执行生产构建产出静态文件。构建完成后产物位于.wasp/build/web-app/build/目录下它是一组纯静态文件HTML、JS、CSS 与静态资源可以直接部署到任意静态托管平台如 Netlify、Cloudflare Pages 等部署方式就是把.wasp/build/web-app/build/目录的内容托管出去。重点提醒来自原文档的 caution如果你在项目中还定义了其他客户端侧环境变量开发模式下写在.env.client中在构建时也必须把它们一并追加到上面的命令里。例如npm install REACT_APP_API_URLurl_to_wasp_backend REACT_APP_SOME_OTHER_VAR_NAMEsomeothervalue npm run build否则这些客户端变量在生产构建产物中不会存在依赖它们的代码会在运行时拿到未定义值。为什么客户端环境变量必须写在构建命令里这与客户端环境变量在 Wasp 中的工作方式直接相关详见 部署环境变量文档开发阶段你可以在项目根目录创建.env.client和.env.server两个文件来分别管理客户端与服务端变量但部署阶段这两个文件都会被忽略必须改用其他方式提供变量对客户端而言变量必须在构建命令中以内联方式传入。它们会被注入到客户端 JS 代码里因此是公开、任何人可读的——绝对不要在客户端变量中存放密钥如 API 密钥密钥应放入服务端环境变量与服务器环境变量不同不能也不应该通过在托管平台上设置环境变量来为客户端代码提供变量——因为构建完成后的客户端只是一堆静态文件运行期读取不到任何宿主环境变量。其底层原理文档中专门有一段 How it works构建过程中Wasp 会把客户端代码里的import.meta.env.REACT_APP_SOME_VAR_NAME全部替换为你在命令中提供的实际值。替换发生在构建阶段因此值是直接注入进静态产物文件中的——这正是 Vite 在生产构建中对import.meta.env的标准替换机制Vite 文档中的 Production Replacement。在代码层面对应的产物位置也有明确佐证Wasp 客户端工具链基于 Vite 构建生成器在 WebAppGenerator.hs 中定义了完整的产物路径链.wasp/build→web-app→build。这与你手动执行cd .wasp/build/web-app npm run build后看到的输出目录完全一致。在客户端代码中如何引用这些变量在生产构建中传入REACT_APP_API_URL等变量后客户端代码通过wasp/client暴露的env对象读取详见 项目环境变量文档import { env } from wasp/client // Wasp 内置定义的客户端变量 const apiUrl env.REACT_APP_API_URL // 用户自定义的客户端变量 const analyticsId env.REACT_APP_ANALYTICS_ID你也可以直接使用import.meta.env.REACT_APP_SOME_VAR_NAME但官方不推荐——因为import.meta.env未经校验缺失的变量可能引发运行时错误。更稳妥的做法是在 src/env.ts 中用 Zod 定义clientEnvValidationSchema通过wasp/env的defineEnvValidationSchema并在main.wasp的app声明中通过client.envValidationSchema注册让 Wasp 在验证import.meta.env时把内置 schema 与你自定义的 schema 合并执行。REACT_APP_API_URL的默认值与语义REACT_APP_API_URL是 Wasp 预置的客户端环境变量客户端用它作为访问后端服务器的 URL。在开发模式下它的默认值为http://localhost:3001即本地 Wasp 服务器默认监听地址因此在wasp start开发时通常无需显式配置而生产构建时必须显式传入已部署后端的地址否则客户端发起的 API 请求将指向错误位置前后端无法联通。结合部署场景的完整实践方式一PaaS 全流程中的客户端构建在 PaaS 部署文档 中_building-the-web-client.md这段内容被作为通用步骤嵌入到各平台的部署指南里。以 Railway 为例部署客户端的完整链路是# 1. 进入客户端工程目录 cd .wasp/build/web-app # 2. 用服务器域名作为 REACT_APP_API_URL 完成生产构建 npm install REACT_APP_API_URLurl_to_wasp_backend npm run build # 3. 链接到 Railway 项目配置静态托管 railway link cp -r build dist # 编写 Dockerfile基于 gostatic与 .dockerignore然后 railway up 部署以 Netlify 为例客户端专用静态托管# 同样先构建客户端 cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build # 使用 Netlify CLI 部署先试部署再发布到生产 npx netlify-cli deploy npx netlify-cli deploy --prod以 Cloudflare Pages 为例cd .wasp/build/web-app npm install REACT_APP_API_URLurl_to_wasp_backend npm run build npx wrangler pages deploy ./build --commit-dirtytrue --branchmain无论部署到哪个平台客户端上线后都别忘了把客户端 URL 设置到服务端环境变量WASP_WEB_CLIENT_URL中例如flyctl secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client否则服务端的邮件链接、OAuth 回调等功能将无法正确跳转回前端。方式二用 Wasp CLI 一键部署替代手工构建如果你不想手动执行上述三步可以直接使用 Wasp CLI 的部署命令。Wasp CLI 会替你完成服务器部署、客户端部署和数据库配置并支持一条命令重新部署更新应用。详见 Wasp CLI 部署文档。不过即使使用 CLI理解本文的手动构建流程仍然有价值——它揭示了 CLI 在背后执行的本质操作也有助于排查部署问题。客户端部署的额外注意点SPA 路由回退fallbackWasp 的客户端是一个单页应用SPA所有路由由客户端处理。因此静态托管平台必须把未知路径回退到index.html部署到 Netlify 时Wasp 默认会在.wasp/build/web-app/下生成netlify.tomlNetlify CLI 会自动读取它并配置好 URL 重定向到index.html。如果你改用其他方式如 CI 部署务必确保netlify.toml被平台拾取或手动配置重定向部署到 Cloudflare Pages 时平台会自动将所有路径重定向到index.html无需额外配置。每次wasp build之后都要重新构建客户端wasp build每次都会重建实际上会清空.wasp/build/目录因此.wasp/build/web-app及其中的构建产物都会被覆盖。任何涉及客户端的部署脚本如 PaaS 文档 中 Railway 的deploy_client.sh自动化脚本都需要在每次wasp build之后重新执行npm install REACT_APP_API_URL... npm run build。同样地如果直接把fly.toml等部署配置放在.wasp/build/下也会在重新构建时被清除——文档建议将其复制到版本管理目录如项目根目录并通过--config参数引用。常见问题排查症状原因与排查方向构建命令报错提示 SQLite项目仍在使用默认 SQLite 数据库需先按 数据模型文档 切换为 PostgreSQL 后再wasp build前端能打开但接口全部失败REACT_APP_API_URL未传入、传错或指向了未部署的后端确认值必须与已部署服务器的真实 URL 一致自定义客户端变量在生产端为undefined构建命令遗漏了该变量需与REACT_APP_API_URL一同以内联方式传入前端刷新出现 404静态托管平台未配置 SPA 路由回退到index.html参照上文 Netlify / Cloudflare 的说明处理邮件、OAuth 跳转指向错误地址服务端缺少或错误配置了WASP_WEB_CLIENT_URL需设置为已部署客户端 URL小结Wasp 的前端部署本质上是构建静态文件 静态托管两个环节wasp build生成客户端工程 → 在.wasp/build/web-app中执行npm install REACT_APP_API_URLurl_to_wasp_backend npm run build→ 把.wasp/build/web-app/build/的静态产物部署到任意静态托管平台。核心要点有三个REACT_APP_API_URL必须在构建命令中显式传入已部署后端地址其他客户端变量同样要在构建时内联注入它们会进入公开的静态产物严禁放密钥每次重新wasp build后都必须重做客户端构建与部署。掌握这条手动链路后你既可以用它把前端部署到任何你偏好的平台也能更深入地理解 Wasp CLI 一键部署背后的工作原理。【免费下载链接】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），仅供参考
