尧图网站建设 
Wasp 前端静态构建指南手动构建 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生成的可部署代码中后端以 Docker 镜像形式交付而前端则是一个纯粹的静态站点需要你手动执行安装依赖与生产构建两个步骤。本指南聚焦于如何手动构建 Wasp 的 Web Client涵盖构建目录定位、REACT_APP_API_URL等客户端环境变量的注入方式、产物目录结构以及如何将这些静态文件交付给任意静态托管平台并附以仓库源码层面的实现佐证。手动构建 Web Client 的核心命令Wasp 应用执行wasp build之后会在项目的.wasp/build/即构建输出目录.wasp/out/下生成整个应用的可部署代码其中前端代码位于.wasp/build/web-app目录。构建 Web Client 分两步先进入该目录再执行安装依赖 注入 API 地址 生产构建。第一步定位到前端构建目录cd .wasp/build/web-app第二步安装依赖并执行生产构建npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你已经部署好的 Wasp 后端 API 服务器地址。之所以要求后端先就绪是因为前端在构建期就需要把 API 地址烧录进静态产物中——这一点在 paas.md 的客户端部署小节 中有明确说明。命令执行完毕后构建产物会出现在.wasp/build/web-app/build/目录中即 paas.md 中提到的构建命令会把 Web Client 输出到.wasp/build/web-app/目录下的build/子目录。由于构建结果只是一批静态文件你可以把.wasp/build/web-app/build/中的全部内容部署到任意静态托管平台如 Netlify、Cloudflare Pages 等无需任何服务端运行时。为什么必须在构建命令中注入客户端环境变量客户端环境变量的本质构建期注入在 项目环境变量文档 中 Wasp 明确区分了两类环境变量客户端环境变量Client Env Vars在构建过程中被注入到客户端 JavaScript 代码里对任何访问网站的人公开可读因此绝不能在客户端环境变量中存放密钥如密钥型 API Key应放入服务端环境变量服务端环境变量Server Env Vars只存在于服务端运行环境对外不可见适合存放密钥。生产环境与开发环境的注入方式截然不同。开发时你可以在项目根目录使用.env.client/.env.server文件见 project/env-vars.md 的 Defining Env Vars in Development 小节但在部署时.env.client和.env.server都会被忽略必须改用其他方式提供变量——这正是 deployment/env-vars.md 反复强调的要点。REACT_APP_API_URL客户端连接后端的唯一通道在 project/env-vars.md 的客户端通用配置小节 中Wasp 定义了唯一的内置客户端环境变量变量名类型是否必填默认值说明REACT_APP_API_URLURL否http://localhost:3001客户端将其用作服务器 URL虽然表格中标为非必填但请注意默认值指向的是开发环境地址http://localhost:3001。在手动构建生产客户端时如果不显式覆盖它产物中的 API 地址会停留在本地回环地址浏览器里用户的请求将打到用户自己的机器上导致前后端完全无法联通。因此生产构建命令中显式指定REACT_APP_API_URLurl_to_wasp_backend是必须养成的习惯。Wasp 内置的客户端环境变量远不止这一个。在原文档警告中提到的其他客户端环境变量指的是你在src/env.ts等位置通过defineEnvValidationSchema自定义的REACT_APP_*系列变量以及 OAuth 类功能可能涉及的客户端侧配置。凡是客户端代码中通过import.meta.env.REACT_APP_*读取的变量都必须一并写进这条构建命令。例如npm install REACT_APP_API_URLurl_to_wasp_backend REACT_APP_ANALYTICS_IDUA-XXXXX npm run build注入机制构建期的静态替换为什么必须在命令行提供而不是在托管平台设置deployment/env-vars.md 的 How it works 小节 给出了底层机制Wasp 会在构建过程中把客户端代码里所有import.meta.env.REACT_APP_SOME_VAR_NAME的出现位置替换为你在构建命令中提供的值。也就是说值在构建期就烧写进静态文件了。客户端部署上线后只是一堆静态文件无论你在托管平台怎么配置环境变量客户端代码都不会再读取它们——静态文件里只有构建时注入的那份值。这一机制在仓库源码中同样有印证Wasp 的部署工具链在 waspc/data/packages/deploy/src/common/clientApp.ts 中定义常量serverUrlEnvVarName REACT_APP_API_URL并在buildClient函数中先执行npm install再以{ ...process.env, [serverUrlEnvVarName]: serverUrl }的方式把REACT_APP_API_URL注入环境后调用vite build——与你手动执行两条命令做的事情完全一致。Wasp 的代码生成器同样把REACT_APP_API_URL视为后端地址的环境变量名见 waspc/src/Wasp/Generator/WebAppGenerator/Common.hs 中的serverUrlEnvVarName定义。构建产物的目录结构与验证手动构建完成后.wasp/build/web-app/下的典型结构如下.wasp/build/web-app/ ├── build/ # 生产构建的静态产物部署这一整个目录 │ ├── index.html │ ├── assets/ │ │ └── index-*.js / index-*.css │ └── ... ├── package.json ├── vite.config.* └── ...其中build/目录就是最终要交付给静态托管平台的内容。部署时把build/指向托管平台的发布目录或把其中文件上传到站点根目录即可。有一点需要特别注意Wasp 的客户端是一个单页应用SPA路由在客户端完成因此静态托管方必须配置将任意路径重定向到index.html的规则否则用户直接访问/some/route这类深链接时会 404。这一点在 paas.md 的 Netlify 小节 与 Cloudflare 小节 中都有专门提醒。另外要注意.wasp/build/即.wasp/out/是构建产物目录每次执行wasp build都会被清空重建。如果手动部署流程中依赖了该目录下的人工配置例如为 Fly.io 保留的fly.tomlpaas.md 的 Redeploying After Wasp Builds 小节 建议把它复制到版本管理目录再用--config参数引用。手动构建客户端 vs Wasp Deploy 一键部署对于 Fly.io 与 Railway 这类同时承载后端、前端与数据库的平台Wasp 提供了wasp deploy命令wasp deploy fly/wasp deploy railway自动化完成构建客户端 → 注入REACT_APP_API_URL→ 部署的全流程见 paas.md 中的 Wasp Deploy 推荐说明。而本指南的手动构建流程主要适用于以下场景部署到纯静态托管平台如 Netlify、Cloudflare Pages——平台只负责托管静态文件前端构建必须由你在本地或 CI 中手动完成在 CI/CD 流水线中自定义构建步骤后端已部署完毕需要单独构建并发布前端。原文档中针对 Netlify 与 Cloudflare 均提供了完整的 GitHub Actions 工作流示例见 paas.md 的 Netlify GitHub Actions 小节其核心步骤正是本指南的命令先cd ./.wasp/build/web-app npm install再以REACT_APP_API_URL${{ secrets.WASP_SERVER_URL }} npm run build构建最后把build/目录部署上线。部署后的收尾回填服务端环境变量客户端上线后别忘了一个反向的收尾动作把你最终的客户端 URL 回填到服务端的WASP_WEB_CLIENT_URL环境变量中。服务端依赖该变量在邮件、OAuth 登录跳转等场景中拼装指向客户端的链接见 project/env-vars.md 的服务端通用配置小节。在 paas.md 的 Fly.io 小节 中有明确提醒如果不知道客户端 URL可以先把服务端部署起来等客户端部署完成后再用fly secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client补上。服务端环境变量与客户端不同它们是在服务端运行时通过平台机制提供的例如fly secrets set详细清单可对照 project/env-vars.md 的服务端环境变量列表 逐一核对尤其是DATABASE_URL、JWT_SECRET随机字符串至少 32 字符、WASP_SERVER_URL等必填项。小结手动构建 Wasp Web Client 的完整流程可归纳为四步执行wasp build生成可部署代码 → 进入.wasp/build/web-app→ 以REACT_APP_API_URL后端地址及所有自定义REACT_APP_*变量执行npm install npm run build→ 将.wasp/build/web-app/build/部署到静态托管平台并配置 SPA 重定向规则最后回填WASP_WEB_CLIENT_URL。理解客户端环境变量是构建期注入、静态文件不再读取运行时环境这一底层机制能帮助你避免线上前后端地址错配、深链接 404 等常见部署问题。【免费下载链接】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 Client 与生产环境变量注入
Wasp 前端静态构建指南手动构建 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生成的可部署代码中后端以 Docker 镜像形式交付而前端则是一个纯粹的静态站点需要你手动执行安装依赖与生产构建两个步骤。本指南聚焦于如何手动构建 Wasp 的 Web Client涵盖构建目录定位、REACT_APP_API_URL等客户端环境变量的注入方式、产物目录结构以及如何将这些静态文件交付给任意静态托管平台并附以仓库源码层面的实现佐证。手动构建 Web Client 的核心命令Wasp 应用执行wasp build之后会在项目的.wasp/build/即构建输出目录.wasp/out/下生成整个应用的可部署代码其中前端代码位于.wasp/build/web-app目录。构建 Web Client 分两步先进入该目录再执行安装依赖 注入 API 地址 生产构建。第一步定位到前端构建目录cd .wasp/build/web-app第二步安装依赖并执行生产构建npm install REACT_APP_API_URLurl_to_wasp_backend npm run build其中url_to_wasp_backend是你已经部署好的 Wasp 后端 API 服务器地址。之所以要求后端先就绪是因为前端在构建期就需要把 API 地址烧录进静态产物中——这一点在 paas.md 的客户端部署小节 中有明确说明。命令执行完毕后构建产物会出现在.wasp/build/web-app/build/目录中即 paas.md 中提到的构建命令会把 Web Client 输出到.wasp/build/web-app/目录下的build/子目录。由于构建结果只是一批静态文件你可以把.wasp/build/web-app/build/中的全部内容部署到任意静态托管平台如 Netlify、Cloudflare Pages 等无需任何服务端运行时。为什么必须在构建命令中注入客户端环境变量客户端环境变量的本质构建期注入在 项目环境变量文档 中 Wasp 明确区分了两类环境变量客户端环境变量Client Env Vars在构建过程中被注入到客户端 JavaScript 代码里对任何访问网站的人公开可读因此绝不能在客户端环境变量中存放密钥如密钥型 API Key应放入服务端环境变量服务端环境变量Server Env Vars只存在于服务端运行环境对外不可见适合存放密钥。生产环境与开发环境的注入方式截然不同。开发时你可以在项目根目录使用.env.client/.env.server文件见 project/env-vars.md 的 Defining Env Vars in Development 小节但在部署时.env.client和.env.server都会被忽略必须改用其他方式提供变量——这正是 deployment/env-vars.md 反复强调的要点。REACT_APP_API_URL客户端连接后端的唯一通道在 project/env-vars.md 的客户端通用配置小节 中Wasp 定义了唯一的内置客户端环境变量变量名类型是否必填默认值说明REACT_APP_API_URLURL否http://localhost:3001客户端将其用作服务器 URL虽然表格中标为非必填但请注意默认值指向的是开发环境地址http://localhost:3001。在手动构建生产客户端时如果不显式覆盖它产物中的 API 地址会停留在本地回环地址浏览器里用户的请求将打到用户自己的机器上导致前后端完全无法联通。因此生产构建命令中显式指定REACT_APP_API_URLurl_to_wasp_backend是必须养成的习惯。Wasp 内置的客户端环境变量远不止这一个。在原文档警告中提到的其他客户端环境变量指的是你在src/env.ts等位置通过defineEnvValidationSchema自定义的REACT_APP_*系列变量以及 OAuth 类功能可能涉及的客户端侧配置。凡是客户端代码中通过import.meta.env.REACT_APP_*读取的变量都必须一并写进这条构建命令。例如npm install REACT_APP_API_URLurl_to_wasp_backend REACT_APP_ANALYTICS_IDUA-XXXXX npm run build注入机制构建期的静态替换为什么必须在命令行提供而不是在托管平台设置deployment/env-vars.md 的 How it works 小节 给出了底层机制Wasp 会在构建过程中把客户端代码里所有import.meta.env.REACT_APP_SOME_VAR_NAME的出现位置替换为你在构建命令中提供的值。也就是说值在构建期就烧写进静态文件了。客户端部署上线后只是一堆静态文件无论你在托管平台怎么配置环境变量客户端代码都不会再读取它们——静态文件里只有构建时注入的那份值。这一机制在仓库源码中同样有印证Wasp 的部署工具链在 waspc/data/packages/deploy/src/common/clientApp.ts 中定义常量serverUrlEnvVarName REACT_APP_API_URL并在buildClient函数中先执行npm install再以{ ...process.env, [serverUrlEnvVarName]: serverUrl }的方式把REACT_APP_API_URL注入环境后调用vite build——与你手动执行两条命令做的事情完全一致。Wasp 的代码生成器同样把REACT_APP_API_URL视为后端地址的环境变量名见 waspc/src/Wasp/Generator/WebAppGenerator/Common.hs 中的serverUrlEnvVarName定义。构建产物的目录结构与验证手动构建完成后.wasp/build/web-app/下的典型结构如下.wasp/build/web-app/ ├── build/ # 生产构建的静态产物部署这一整个目录 │ ├── index.html │ ├── assets/ │ │ └── index-*.js / index-*.css │ └── ... ├── package.json ├── vite.config.* └── ...其中build/目录就是最终要交付给静态托管平台的内容。部署时把build/指向托管平台的发布目录或把其中文件上传到站点根目录即可。有一点需要特别注意Wasp 的客户端是一个单页应用SPA路由在客户端完成因此静态托管方必须配置将任意路径重定向到index.html的规则否则用户直接访问/some/route这类深链接时会 404。这一点在 paas.md 的 Netlify 小节 与 Cloudflare 小节 中都有专门提醒。另外要注意.wasp/build/即.wasp/out/是构建产物目录每次执行wasp build都会被清空重建。如果手动部署流程中依赖了该目录下的人工配置例如为 Fly.io 保留的fly.tomlpaas.md 的 Redeploying After Wasp Builds 小节 建议把它复制到版本管理目录再用--config参数引用。手动构建客户端 vs Wasp Deploy 一键部署对于 Fly.io 与 Railway 这类同时承载后端、前端与数据库的平台Wasp 提供了wasp deploy命令wasp deploy fly/wasp deploy railway自动化完成构建客户端 → 注入REACT_APP_API_URL→ 部署的全流程见 paas.md 中的 Wasp Deploy 推荐说明。而本指南的手动构建流程主要适用于以下场景部署到纯静态托管平台如 Netlify、Cloudflare Pages——平台只负责托管静态文件前端构建必须由你在本地或 CI 中手动完成在 CI/CD 流水线中自定义构建步骤后端已部署完毕需要单独构建并发布前端。原文档中针对 Netlify 与 Cloudflare 均提供了完整的 GitHub Actions 工作流示例见 paas.md 的 Netlify GitHub Actions 小节其核心步骤正是本指南的命令先cd ./.wasp/build/web-app npm install再以REACT_APP_API_URL${{ secrets.WASP_SERVER_URL }} npm run build构建最后把build/目录部署上线。部署后的收尾回填服务端环境变量客户端上线后别忘了一个反向的收尾动作把你最终的客户端 URL 回填到服务端的WASP_WEB_CLIENT_URL环境变量中。服务端依赖该变量在邮件、OAuth 登录跳转等场景中拼装指向客户端的链接见 project/env-vars.md 的服务端通用配置小节。在 paas.md 的 Fly.io 小节 中有明确提醒如果不知道客户端 URL可以先把服务端部署起来等客户端部署完成后再用fly secrets set WASP_WEB_CLIENT_URLurl_of_deployed_client补上。服务端环境变量与客户端不同它们是在服务端运行时通过平台机制提供的例如fly secrets set详细清单可对照 project/env-vars.md 的服务端环境变量列表 逐一核对尤其是DATABASE_URL、JWT_SECRET随机字符串至少 32 字符、WASP_SERVER_URL等必填项。小结手动构建 Wasp Web Client 的完整流程可归纳为四步执行wasp build生成可部署代码 → 进入.wasp/build/web-app→ 以REACT_APP_API_URL后端地址及所有自定义REACT_APP_*变量执行npm install npm run build→ 将.wasp/build/web-app/build/部署到静态托管平台并配置 SPA 重定向规则最后回填WASP_WEB_CLIENT_URL。理解客户端环境变量是构建期注入、静态文件不再读取运行时环境这一底层机制能帮助你避免线上前后端地址错配、深链接 404 等常见部署问题。【免费下载链接】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），仅供参考