Wasp 子目录部署指南baseDir 与 WASP_WEB_CLIENT_URL 环境变量的正确配置【免费下载链接】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 客户端配置中的baseDir选项展开核心解决将 Wasp 应用部署到域名子目录如https://example.com/my-app时如何正确配置WASP_WEB_CLIENT_URL环境变量这一实战问题。读完本文你将掌握baseDir在 Wasp 中的完整作用链路Vite 构建配置与 React Router 路由基线并能根据官方警告正确设置配套环境变量避免资源加载与跨域校验失败。为什么需要 baseDir子目录部署场景大多数 Web 应用直接部署在域名的根路径如https://example.com此时所有路由和静态资源都从根路径开始解析无需额外配置。但在以下场景中你需要将应用挂载到域名的某个子目录下一个域名下同时托管多个独立应用如博客、后台管理系统、营销页面每个应用占用一个子路径借助 CDN、反向代理或静态托管服务将前端构建产物放在某个路径前缀之下与已有系统共享域名需要避免路由冲突。Wasp 为此提供了客户端配置项client.baseDir。官方文档在 version-0.18 客户端配置文档 与当前 客户端配置文档 的 Base Directory 一节中均对此做了说明一旦设置baseDirWasp 会保证在从子目录提供应用时路由工作正常、所有静态资源也从该子目录路径下加载。配置 baseDir两种配置语法在 Wasp 0.18 版本中应用配置写在main.wasp文件里采用声明式 Wasp DSL 语法app MyApp { title: My app, // ... client: { baseDir: /my-app, } }在新版 TypeScript 规范main.wasp.ts中写法如下import { app } from wasp.sh/spec export default app({ name: MyApp, client: { baseDir: /my-app, }, // ... })baseDir的值是一个以/开头的字符串从 waspc/data/packages/spec/src/appSpec.ts 中的类型定义baseDir: Optional/${string}可以看出规范强制要求以斜杠开头。官方文档给出的效果描述是如果你从https://example.com/my-app提供服务路由器会正确工作所有资源也会从https://example.com/my-app加载。baseDir 在源码中的两层作用从生成器的模板源码可以清楚看到baseDir具体控制了两个层面第一层Vite 构建基路径base。在 waspConfig.ts 中baseDir被注入到 Vite 的强制配置项baseconst forcedOptions { base: { baseDir }, envPrefix: REACT_APP_, build.outDir: { clientBuildDirPath }, // ... }Vite 的base选项决定了构建产物中所有静态资源引用的公共路径前缀这正是所有资源都从子目录加载的底层实现。因此 custom-vite-config.md 明确标注Vite 的base项基于client.baseDir派生属于无法自定义的强制选项因为 Wasp 需要将 React Router 的basename设置为同一个值二者必须保持一致。第二层React Router 的basename。在 client-entry.tsx 中baseDir被注入到路由器的basename属性const router createBrowserRouter({ routeObjects.importIdentifier }, { basename: { baseDir }, // ... })basename是 React Router 用于解析所有路由路径的前缀它保证了浏览器地址栏中的路径如/my-app/settings能被正确映射到应用内部路由/settings这就是路由器在子目录下正常工作的实现原理。核心警告WASP_WEB_CLIENT_URL 必须包含 baseDir这是本主题最关键、也是最容易踩坑的一点。官方在 _baseDirEnvNote.md 中以caution 级别给出明确警告如果你设置了baseDir选项请确保WASP_WEB_CLIENT_URL环境变量也包含该基础目录。例如如果你从https://example.com/my-app提供应用那么WASP_WEB_CLIENT_URL也应设置为https://example.com/my-app而不能只是https://example.com。也就是说baseDir与WASP_WEB_CLIENT_URL必须指向同一个完整 URL。这个警告被嵌入到客户端配置文档的 Base Directory 小节以及 API Reference 中baseDir选项的说明处见 version-0.18 的 client-config.md足见其重要性——凡是使用baseDir的开发者都必须遵守这一配套约束。为什么 WASP_WEB_CLIENT_URL 不能只写根路径WASP_WEB_CLIENT_URL是 Wasp 的服务器端环境变量在 ServerGenerator/Common.hs 中定义clientUrlEnvVarName :: String clientUrlEnvVarName WASP_WEB_CLIENT_URL服务器使用该变量来感知前端应用的真实访问地址用于 CORS 校验、链接/回调 URL 生成等场景。从 ChangeLog.md 的历史记录可以看到WASP_WEB_CLIENT_URL已成为为提升 CORS 安全性而必需的required环境变量在生产环境中应指向前端应用实际被托管的 URL。如果baseDir是/my-app而WASP_WEB_CLIENT_URL仍写成https://example.com那么服务器认为的前端地址与浏览器实际访问前端的地址https://example.com/my-app就不一致会导致 CORS 校验不通过、回调 URL 拼接错误等连锁问题。这也是官方文档将该警告放在 caution 级别、并明确要求包含基础目录的根本原因。开发模式下由 Wasp 自动管理值得一提的是在开发环境wasp start中你通常无需手动操心这个变量。从 AppComponentUrls.hs 可以看到默认的客户端 URL 由makeDefaultDevClientUrl生成其中path直接取自getBaseDirmakeDefaultDevClientUrl spec Local {port defaultDevClientPort, path Just $ WebAppG.getBaseDir spec}而 ChangeLog.md 也记录Wasp 现在会在开发模式下自行管理应用的 URL开发者手动设置WASP_WEB_CLIENT_URL反而会报错。因此本文警告主要针对生产部署场景——构建并托管到子目录时必须手动保证二者一致。生产环境中的正确配置方式手动设置环境变量在部署到生产环境时你需要为服务器进程提供完整的前端地址。环境变量文件如.env.server中的正确写法# 应用部署在子目录 /my-app 下 WASP_WEB_CLIENT_URLhttps://example.com/my-app WASP_SERVER_URLhttps://example.com注意WASP_WEB_CLIENT_URL必须包含/my-app路径且末尾是否带斜杠应与你实际托管路径保持一致。部署平台自动注入Wasp 的官方部署平台插件会自动完成这一设置无需手动干预。以 Fly.io 为例在 fly 的 setup.ts 中部署初始化时会自动写入WASP_WEB_CLIENT_URL${getFlyAppUrl(deploymentInstructions.clientFlyAppName)}, WASP_SERVER_URL${getFlyAppUrl(deploymentInstructions.serverFlyAppName)},同理Railway 部署插件在 railway 的 setup.ts 中也会注入WASP_WEB_CLIENT_URL${clientUrl}。也就是说使用 Wasp 官方部署流程时平台会基于前端应用的真实地址自动生成该变量但如果你的前端应用实际挂载在子目录下例如通过反向代理将/my-app/*转发到前端服务就需要确认生成的 URL 与代理后的实际访问地址一致必要时手动覆盖。变更端口时的连带提醒ChangeLog.md 中还记录了一条关联经验当自定义开发服务器端口时也需要同步更新.env.server中的WASP_WEB_CLIENT_URL——这从侧面印证了该变量在整个开发/部署生命周期中都与前端真实地址严格绑定任何改变前端访问路径的操作端口、子目录、域名都必须同步修正它。最佳实践清单总结baseDir与WASP_WEB_CLIENT_URL的配套使用要点设置baseDir时在main.wasp或main.wasp.ts的client字段中声明值为以/开头的子路径如/my-app生产部署时将WASP_WEB_CLIENT_URL设置为包含该子路径的完整 URL例如https://example.com/my-app绝不能只写https://example.com不要手动修改 Vite 的base——它由 Wasp 根据baseDir强制派生参见 custom-vite-config.md手动覆盖会被生成器拒绝或导致路由与资源路径不一致依赖官方部署流程时确认平台注入的WASP_WEB_CLIENT_URL与经过反向代理后的实际访问地址一致涉及路径重写时需手动校正开发模式下无需手动设置该变量Wasp 会自动基于baseDir生成默认开发 URL。遵循以上原则你的 Wasp 应用就能稳定地运行在域名的任意子目录下同时保持路由、静态资源与跨域校验的完整一致性。相关完整配置说明可进一步参考 客户端配置文档v0.18、客户端配置文档当前版 以及 警告原文。【免费下载链接】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 子目录部署指南：baseDir 与 WASP_WEB_CLIENT_URL 环境变量的正确配置
Wasp 子目录部署指南baseDir 与 WASP_WEB_CLIENT_URL 环境变量的正确配置【免费下载链接】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 客户端配置中的baseDir选项展开核心解决将 Wasp 应用部署到域名子目录如https://example.com/my-app时如何正确配置WASP_WEB_CLIENT_URL环境变量这一实战问题。读完本文你将掌握baseDir在 Wasp 中的完整作用链路Vite 构建配置与 React Router 路由基线并能根据官方警告正确设置配套环境变量避免资源加载与跨域校验失败。为什么需要 baseDir子目录部署场景大多数 Web 应用直接部署在域名的根路径如https://example.com此时所有路由和静态资源都从根路径开始解析无需额外配置。但在以下场景中你需要将应用挂载到域名的某个子目录下一个域名下同时托管多个独立应用如博客、后台管理系统、营销页面每个应用占用一个子路径借助 CDN、反向代理或静态托管服务将前端构建产物放在某个路径前缀之下与已有系统共享域名需要避免路由冲突。Wasp 为此提供了客户端配置项client.baseDir。官方文档在 version-0.18 客户端配置文档 与当前 客户端配置文档 的 Base Directory 一节中均对此做了说明一旦设置baseDirWasp 会保证在从子目录提供应用时路由工作正常、所有静态资源也从该子目录路径下加载。配置 baseDir两种配置语法在 Wasp 0.18 版本中应用配置写在main.wasp文件里采用声明式 Wasp DSL 语法app MyApp { title: My app, // ... client: { baseDir: /my-app, } }在新版 TypeScript 规范main.wasp.ts中写法如下import { app } from wasp.sh/spec export default app({ name: MyApp, client: { baseDir: /my-app, }, // ... })baseDir的值是一个以/开头的字符串从 waspc/data/packages/spec/src/appSpec.ts 中的类型定义baseDir: Optional/${string}可以看出规范强制要求以斜杠开头。官方文档给出的效果描述是如果你从https://example.com/my-app提供服务路由器会正确工作所有资源也会从https://example.com/my-app加载。baseDir 在源码中的两层作用从生成器的模板源码可以清楚看到baseDir具体控制了两个层面第一层Vite 构建基路径base。在 waspConfig.ts 中baseDir被注入到 Vite 的强制配置项baseconst forcedOptions { base: { baseDir }, envPrefix: REACT_APP_, build.outDir: { clientBuildDirPath }, // ... }Vite 的base选项决定了构建产物中所有静态资源引用的公共路径前缀这正是所有资源都从子目录加载的底层实现。因此 custom-vite-config.md 明确标注Vite 的base项基于client.baseDir派生属于无法自定义的强制选项因为 Wasp 需要将 React Router 的basename设置为同一个值二者必须保持一致。第二层React Router 的basename。在 client-entry.tsx 中baseDir被注入到路由器的basename属性const router createBrowserRouter({ routeObjects.importIdentifier }, { basename: { baseDir }, // ... })basename是 React Router 用于解析所有路由路径的前缀它保证了浏览器地址栏中的路径如/my-app/settings能被正确映射到应用内部路由/settings这就是路由器在子目录下正常工作的实现原理。核心警告WASP_WEB_CLIENT_URL 必须包含 baseDir这是本主题最关键、也是最容易踩坑的一点。官方在 _baseDirEnvNote.md 中以caution 级别给出明确警告如果你设置了baseDir选项请确保WASP_WEB_CLIENT_URL环境变量也包含该基础目录。例如如果你从https://example.com/my-app提供应用那么WASP_WEB_CLIENT_URL也应设置为https://example.com/my-app而不能只是https://example.com。也就是说baseDir与WASP_WEB_CLIENT_URL必须指向同一个完整 URL。这个警告被嵌入到客户端配置文档的 Base Directory 小节以及 API Reference 中baseDir选项的说明处见 version-0.18 的 client-config.md足见其重要性——凡是使用baseDir的开发者都必须遵守这一配套约束。为什么 WASP_WEB_CLIENT_URL 不能只写根路径WASP_WEB_CLIENT_URL是 Wasp 的服务器端环境变量在 ServerGenerator/Common.hs 中定义clientUrlEnvVarName :: String clientUrlEnvVarName WASP_WEB_CLIENT_URL服务器使用该变量来感知前端应用的真实访问地址用于 CORS 校验、链接/回调 URL 生成等场景。从 ChangeLog.md 的历史记录可以看到WASP_WEB_CLIENT_URL已成为为提升 CORS 安全性而必需的required环境变量在生产环境中应指向前端应用实际被托管的 URL。如果baseDir是/my-app而WASP_WEB_CLIENT_URL仍写成https://example.com那么服务器认为的前端地址与浏览器实际访问前端的地址https://example.com/my-app就不一致会导致 CORS 校验不通过、回调 URL 拼接错误等连锁问题。这也是官方文档将该警告放在 caution 级别、并明确要求包含基础目录的根本原因。开发模式下由 Wasp 自动管理值得一提的是在开发环境wasp start中你通常无需手动操心这个变量。从 AppComponentUrls.hs 可以看到默认的客户端 URL 由makeDefaultDevClientUrl生成其中path直接取自getBaseDirmakeDefaultDevClientUrl spec Local {port defaultDevClientPort, path Just $ WebAppG.getBaseDir spec}而 ChangeLog.md 也记录Wasp 现在会在开发模式下自行管理应用的 URL开发者手动设置WASP_WEB_CLIENT_URL反而会报错。因此本文警告主要针对生产部署场景——构建并托管到子目录时必须手动保证二者一致。生产环境中的正确配置方式手动设置环境变量在部署到生产环境时你需要为服务器进程提供完整的前端地址。环境变量文件如.env.server中的正确写法# 应用部署在子目录 /my-app 下 WASP_WEB_CLIENT_URLhttps://example.com/my-app WASP_SERVER_URLhttps://example.com注意WASP_WEB_CLIENT_URL必须包含/my-app路径且末尾是否带斜杠应与你实际托管路径保持一致。部署平台自动注入Wasp 的官方部署平台插件会自动完成这一设置无需手动干预。以 Fly.io 为例在 fly 的 setup.ts 中部署初始化时会自动写入WASP_WEB_CLIENT_URL${getFlyAppUrl(deploymentInstructions.clientFlyAppName)}, WASP_SERVER_URL${getFlyAppUrl(deploymentInstructions.serverFlyAppName)},同理Railway 部署插件在 railway 的 setup.ts 中也会注入WASP_WEB_CLIENT_URL${clientUrl}。也就是说使用 Wasp 官方部署流程时平台会基于前端应用的真实地址自动生成该变量但如果你的前端应用实际挂载在子目录下例如通过反向代理将/my-app/*转发到前端服务就需要确认生成的 URL 与代理后的实际访问地址一致必要时手动覆盖。变更端口时的连带提醒ChangeLog.md 中还记录了一条关联经验当自定义开发服务器端口时也需要同步更新.env.server中的WASP_WEB_CLIENT_URL——这从侧面印证了该变量在整个开发/部署生命周期中都与前端真实地址严格绑定任何改变前端访问路径的操作端口、子目录、域名都必须同步修正它。最佳实践清单总结baseDir与WASP_WEB_CLIENT_URL的配套使用要点设置baseDir时在main.wasp或main.wasp.ts的client字段中声明值为以/开头的子路径如/my-app生产部署时将WASP_WEB_CLIENT_URL设置为包含该子路径的完整 URL例如https://example.com/my-app绝不能只写https://example.com不要手动修改 Vite 的base——它由 Wasp 根据baseDir强制派生参见 custom-vite-config.md手动覆盖会被生成器拒绝或导致路由与资源路径不一致依赖官方部署流程时确认平台注入的WASP_WEB_CLIENT_URL与经过反向代理后的实际访问地址一致涉及路径重写时需手动校正开发模式下无需手动设置该变量Wasp 会自动基于baseDir生成默认开发 URL。遵循以上原则你的 Wasp 应用就能稳定地运行在域名的任意子目录下同时保持路由、静态资源与跨域校验的完整一致性。相关完整配置说明可进一步参考 客户端配置文档v0.18、客户端配置文档当前版 以及 警告原文。【免费下载链接】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），仅供参考