尧图网页设计 
Wasp 自定义 Vite 配置完全指南开发服务器、端口与基础路径定制【免费下载链接】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/waspWasp 在开发阶段用 Vite 托管客户端、在生产阶段用 Vite 打包客户端并允许你在src/client目录下通过vite.config.ts或vite.config.js定制这一流程。本指南以 Wasp 0.11.8 版本官方文档为核心完整讲解 Vite 配置文件的位置、与 Wasp 默认配置的合并机制并给出关闭自动打开浏览器自定义开发端口自定义基础路径三个可直接落地的实战示例同时结合当前仓库源码从实现层面解释 Wasp 到底替你做主了哪些 Vite 配置项以及改动后为什么必须同步更新WASP_WEB_CLIENT_URL。读完你将能安全、可控地改造 Wasp 客户端的前端工程化行为而不破坏其构建链路。Wasp 与 Vite客户端开发与构建的统一引擎Wasp 使用 Vite 完成两件事开发阶段wasp start启动的客户端开发服务器dev server由 Vite 驱动提供模块热更新HMR与即时编译生产阶段Vite 负责将客户端代码打包bundling产出可供部署的静态资源。如果你的项目需要在默认行为之上做定制只需编辑src/client目录下的 Vite 配置文件——在 0.11.8 版本中配置文件即项目内的src/client/vite.config.tsTypeScript 项目或src/client/vite.config.jsJavaScript 项目。Wasp 会将你的配置与 Wasp 默认的 Vite 配置进行合并merge而不是让你从零编写一份完整配置。这一设计保证了即便你只写了几个自定义选项Wasp 赖以运行的客户端入口、路由、环境变量注入等能力依然完好。典型的使用场景包括添加自定义 Vite 插件如 Tailwind、代码混淆、Bundle 分析器定制开发服务器行为端口、是否自动打开浏览器、代理等定制构建过程输出目录、基础路径、依赖预构建等。⚠️ 需要特别小心的是对 Vite 配置的改动可能破坏 Wasp 的客户端构建流程。动手前建议先完整阅读 Wasp 默认生成的 Vite 配置弄清楚哪些值是被 Wasp 锁定的详见下文源码视角一节再做增量修改。配置合并机制你的配置如何与默认配置共存0.11.8 文档明确说明Wasp 会使用你的配置并将其与 Wasp 默认的 Vite 配置合并。从当前仓库源码看这一机制在后续版本中被实现为一个名为wasp()的 Vite 插件其源码注释对合并语义描述得非常精确见 waspConfig.tsVite mergesuserConfigand ourwaspConfigreturned from the plugin. In that merge, primitive values from waspConfig take precedence, and arrays are concatenated.即标量值以 Wasp 的默认值为准数组则做拼接。Wasp 配置中的条目分三类处理强制项Forced存放在forcedOptions中永远以 Wasp 的值为准如果你在vite.config.ts里显式设置了这些项Wasp 会直接抛错要求你删除它们可覆盖项Overridable读取用户配置的值缺省时回落到 Wasp 默认值源码中用useUserValue(userValue, defaultValue)实现可叠加项Additive数组Wasp 只返回自己的条目Vite 在合并时把它们追加到你的配置之后。换句话说文档所述合并本质上是 Wasp 在关键路径上拥有最终决定权而在其余维度上充分放权。这正是能定制与不会定制坏两者之间的平衡点。实战一关闭开发服务器的自动打开浏览器行为wasp start默认会在启动后自动在浏览器中打开应用。若你希望由自己手动打开例如在无头环境、CI 或习惯自己控制浏览器标签时可以通过定制 Vite 的server.open选项实现。JavaScript 项目src/client/vite.config.jsexport default { server: { open: false, }, }TypeScript 项目src/client/vite.config.tsimport { defineConfig } from vite export default defineConfig({ server: { open: false, }, })server.open对应 Vite 开发服务器的启动后自动打开浏览器开关接受布尔值更进阶的用法是传字符串路径如open: /docs指定打开的具体路由。由于这属于可覆盖项范畴Wasp 不会干涉你可以在合并后的配置中放心使用 Vite 的全部server选项。实战二自定义开发服务器端口Wasp 0.11.8 暴露了 Vite 全部的server选项因此你也可以直接修改开发端口JavaScript 项目src/client/vite.config.jsexport default { server: { port: 4000, }, }TypeScript 项目src/client/vite.config.tsimport { defineConfig } from vite export default defineConfig({ server: { port: 4000, }, })同时还必须同步更新项目根目录下.env.server文件中的WASP_WEB_CLIENT_URLWASP_WEB_CLIENT_URLhttp://localhost:4000为什么改端口必须同步更新 WASP_WEB_CLIENT_URL这是本小节最容易踩坑的地方文档对此专门给出了警告。从仓库源码可以确认它的必要性客户端端口通过PORT环境变量传递给 Vite在 WebAppGenerator/Common.hs 中clientPortEnvVarName PORT且刻意不添加WASP_前缀注释说明因为许多部署平台都使用这个环境变量对应的 RunConfig.hs 会把 Wasp 计算出的客户端端口写入PORT。也就是说客户端 dev server 实际监听哪个端口是由 Wasp 协调分配的。服务端通过WASP_WEB_CLIENT_URL定位客户端在 ServerGenerator/Common.hs 中clientUrlEnvVarName WASP_WEB_CLIENT_URL。服务端需要知道客户端在哪来完成诸如登录跳转、服务端渲染等协作。因此当你把端口从默认值改到4000时若不同步更新WASP_WEB_CLIENT_URL服务端仍会指向旧的客户端地址导致跨端口协作如 OAuth 回调、路由跳转失效。端口改了地址变量必须跟着改二者是一体两面。实战三自定义客户端基础路径base默认情况下客户端应用从站点根路径/提供服务。如果你希望把应用挂载在子路径下例如域名后带/my-app/前缀可以定制 Vite 的base选项JavaScript 项目src/client/vite.config.jsexport default { base: /my-app/, }TypeScript 项目src/client/vite.config.tsimport { defineConfig } from vite export default defineConfig({ base: /my-app/, })设置后打包产物的资源引用路径、dev server 的路由前缀都会以/my-app/为基准。例如应用部署在https://example.com/my-app时页面路由与静态资源JS、CSS、图片都将从https://example.com/my-app下正确加载。更推荐的方式使用 client.baseDir从仓库源码看base在 Wasp 中属于被锁定的强制项当前实现的forcedOptions中base由client.baseDir推导而来。因此在更新的 Wasp 版本中官方推荐直接在 Wasp 配置中声明client.baseDir而不是手写 Vite 的base详见 client-config.mdapp MyApp { title: My app, // ... client: { baseDir: /my-app, } }这会让 Wasp 同时完成两件事把 React Router 的basename设为/my-app并把 Vite 的base设为/my-app从而保证路由与静态资源在子路径下同时正确。⚠️ 与端口类似设置baseDir后必须让WASP_WEB_CLIENT_URL包含该基础路径。例如应用部署在https://example.com/my-app时WASP_WEB_CLIENT_URL应设为https://example.com/my-app而非https://example.com完整说明见 _baseDirEnvNote.md。源码视角Wasp 默认 Vite 配置到底替你做主了什么为了让你在自定义时心里有数这里梳理当前仓库中 Wasp 的 Vite 插件实际强制控制的配置项见 waspConfig.ts 中的forcedOptions配置项内部取值为什么不能自定义base由client.baseDir推导默认为/Wasp 会把 React Router 的basename设为相同值二者必须一致envPrefixREACT_APP_Wasp 的客户端环境变量校验依赖此前缀build.outDir.wasp/out/web-app/build构建产物必须落在 Wasp 部署流程期望的位置server.port动态分配经PORT环境变量注入Wasp 需要管理端口以协调服务端与客户端请用wasp start --client-port控制server.strictPorttrue否则端口被占用时 Vite 会静默换端口服务端将指向错误的 URLpreview.port动态分配与server.port同理对应wasp build start的预览服务器若你在vite.config.ts中显式设置了以上任意一项wasp()插件会抛出错误并要求删除源码中的throwIfOverridingForcedOptions会逐项比对并给出提示文案。除强制项外Wasp 的默认配置还做了这些增值处理同样可在 waspConfig.ts 中看到依赖去重resolve.dedupe对react、react-dom、tanstack/react-query、react-router做单实例去重避免出现 Hook 规则违反、QueryClient 重复实例等运行时错误Prisma 客户端别名resolve.alias把.prisma/client导入重定向到node_modules/.prisma/client保证服务端生成的 Prisma Client 能被客户端正确解析Vitest 测试配置默认注入wasp/client/test/setup作为 setup 文件、默认jsdom环境、排除 Wasp 产物目录依赖预构建排除optimizeDeps.exclude排除 Wasp SDK 与内部 libs避免缓存导致 HMR 失效。Wasp 的 Vite 插件整体由多个子插件组成见 wasp.ts 与生成器 VitePluginG.hswasp:config注入上述强制配置与合并逻辑virtual-user-modules/virtual-wasp-modules提供wasp/...虚拟模块与路由等用户模块wasp:env-file开发阶段加载.env.client并以import.meta.env.*注入见 envFile.tswasp:detect-server-imports拦截并报错客户端代码禁止导入服务端代码见 detectServerImports.tswasp:typescript-check仅在生产构建时执行tsc --noEmit类型检查见 typescriptCheck.tswasp:validate-env构建前起一个临时 Vite server 校验客户端环境变量 schema见 validateEnv.ts最后是vitejs/plugin-react与 SSR 相关插件。理解了这份默认配置清单你就能准确判断哪些改动是安全的增量加插件、改server.open、配代理哪些改动会触发 Wasp 的报错动base、envPrefix、build.outDir、server.port。想查看一份真实的、可运行的成品配置可以参考仓库中的启动器模板 basic/vite.config.ts它演示了wasp()插件与 Tailwind 插件并存的标准写法。版本演进提示0.11.8 与当前仓库的差异本文以0.11.8版本文档为核心该版本的定制方式是直接在src/client/vite.config.{js,ts}里写配置Wasp 自动合并。而当前仓库所对应的较新版本已将这一机制演化为显式的wasp()插件vite.config.ts移至项目根目录且必须把wasp()放在plugins数组第一位其他插件如 Tailwind放在其后import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [wasp()], })新版文档还支持通过wasp()插件的reactOptions参数透传vitejs/plugin-react的选项Babel 插件、Fast Refresh 设置、JSX 配置等并提供了端口改用wasp start --client-port 4000控制的 CLI 方式详见 web/docs/project/custom-vite-config.md。如果你的项目基于较新版本建议以新版文档为准两者在Wasp 锁定关键配置、其余放权这一核心思想上是一脉相承的。常见陷阱与排查清单最后汇总本主题下最易出错的三类问题供你在自定义配置后快速自检改了端口忘了改地址server.port变更后.env.server中的WASP_WEB_CLIENT_URL必须同步指向新端口否则服务端与客户端的协作会失联。动了 Wasp 的强制项base、envPrefix、build.outDir、server.port、server.strictPort、preview.port均被 Wasp 锁定在较新版本中显式设置会直接收到报错此时应改用client.baseDir、wasp start --client-port等官方入口。子路径部署只配了一半设置了base/baseDir却没更新WASP_WEB_CLIENT_URL会出现路由正常但资源 404或反向的情况。务必保证 Vite 的base、React Router 的basename、WASP_WEB_CLIENT_URL三者指向同一路径。遵循增量定制、尊重强制项、联动环境变量这三个原则你就能在 Wasp 的约束框架内自由地为客户端接入插件、调整开发服务器与构建行为同时保持wasp start/wasp build全流程的稳定。【免费下载链接】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 自定义 Vite 配置完全指南：开发服务器、端口与基础路径定制
Wasp 自定义 Vite 配置完全指南开发服务器、端口与基础路径定制【免费下载链接】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/waspWasp 在开发阶段用 Vite 托管客户端、在生产阶段用 Vite 打包客户端并允许你在src/client目录下通过vite.config.ts或vite.config.js定制这一流程。本指南以 Wasp 0.11.8 版本官方文档为核心完整讲解 Vite 配置文件的位置、与 Wasp 默认配置的合并机制并给出关闭自动打开浏览器自定义开发端口自定义基础路径三个可直接落地的实战示例同时结合当前仓库源码从实现层面解释 Wasp 到底替你做主了哪些 Vite 配置项以及改动后为什么必须同步更新WASP_WEB_CLIENT_URL。读完你将能安全、可控地改造 Wasp 客户端的前端工程化行为而不破坏其构建链路。Wasp 与 Vite客户端开发与构建的统一引擎Wasp 使用 Vite 完成两件事开发阶段wasp start启动的客户端开发服务器dev server由 Vite 驱动提供模块热更新HMR与即时编译生产阶段Vite 负责将客户端代码打包bundling产出可供部署的静态资源。如果你的项目需要在默认行为之上做定制只需编辑src/client目录下的 Vite 配置文件——在 0.11.8 版本中配置文件即项目内的src/client/vite.config.tsTypeScript 项目或src/client/vite.config.jsJavaScript 项目。Wasp 会将你的配置与 Wasp 默认的 Vite 配置进行合并merge而不是让你从零编写一份完整配置。这一设计保证了即便你只写了几个自定义选项Wasp 赖以运行的客户端入口、路由、环境变量注入等能力依然完好。典型的使用场景包括添加自定义 Vite 插件如 Tailwind、代码混淆、Bundle 分析器定制开发服务器行为端口、是否自动打开浏览器、代理等定制构建过程输出目录、基础路径、依赖预构建等。⚠️ 需要特别小心的是对 Vite 配置的改动可能破坏 Wasp 的客户端构建流程。动手前建议先完整阅读 Wasp 默认生成的 Vite 配置弄清楚哪些值是被 Wasp 锁定的详见下文源码视角一节再做增量修改。配置合并机制你的配置如何与默认配置共存0.11.8 文档明确说明Wasp 会使用你的配置并将其与 Wasp 默认的 Vite 配置合并。从当前仓库源码看这一机制在后续版本中被实现为一个名为wasp()的 Vite 插件其源码注释对合并语义描述得非常精确见 waspConfig.tsVite mergesuserConfigand ourwaspConfigreturned from the plugin. In that merge, primitive values from waspConfig take precedence, and arrays are concatenated.即标量值以 Wasp 的默认值为准数组则做拼接。Wasp 配置中的条目分三类处理强制项Forced存放在forcedOptions中永远以 Wasp 的值为准如果你在vite.config.ts里显式设置了这些项Wasp 会直接抛错要求你删除它们可覆盖项Overridable读取用户配置的值缺省时回落到 Wasp 默认值源码中用useUserValue(userValue, defaultValue)实现可叠加项Additive数组Wasp 只返回自己的条目Vite 在合并时把它们追加到你的配置之后。换句话说文档所述合并本质上是 Wasp 在关键路径上拥有最终决定权而在其余维度上充分放权。这正是能定制与不会定制坏两者之间的平衡点。实战一关闭开发服务器的自动打开浏览器行为wasp start默认会在启动后自动在浏览器中打开应用。若你希望由自己手动打开例如在无头环境、CI 或习惯自己控制浏览器标签时可以通过定制 Vite 的server.open选项实现。JavaScript 项目src/client/vite.config.jsexport default { server: { open: false, }, }TypeScript 项目src/client/vite.config.tsimport { defineConfig } from vite export default defineConfig({ server: { open: false, }, })server.open对应 Vite 开发服务器的启动后自动打开浏览器开关接受布尔值更进阶的用法是传字符串路径如open: /docs指定打开的具体路由。由于这属于可覆盖项范畴Wasp 不会干涉你可以在合并后的配置中放心使用 Vite 的全部server选项。实战二自定义开发服务器端口Wasp 0.11.8 暴露了 Vite 全部的server选项因此你也可以直接修改开发端口JavaScript 项目src/client/vite.config.jsexport default { server: { port: 4000, }, }TypeScript 项目src/client/vite.config.tsimport { defineConfig } from vite export default defineConfig({ server: { port: 4000, }, })同时还必须同步更新项目根目录下.env.server文件中的WASP_WEB_CLIENT_URLWASP_WEB_CLIENT_URLhttp://localhost:4000为什么改端口必须同步更新 WASP_WEB_CLIENT_URL这是本小节最容易踩坑的地方文档对此专门给出了警告。从仓库源码可以确认它的必要性客户端端口通过PORT环境变量传递给 Vite在 WebAppGenerator/Common.hs 中clientPortEnvVarName PORT且刻意不添加WASP_前缀注释说明因为许多部署平台都使用这个环境变量对应的 RunConfig.hs 会把 Wasp 计算出的客户端端口写入PORT。也就是说客户端 dev server 实际监听哪个端口是由 Wasp 协调分配的。服务端通过WASP_WEB_CLIENT_URL定位客户端在 ServerGenerator/Common.hs 中clientUrlEnvVarName WASP_WEB_CLIENT_URL。服务端需要知道客户端在哪来完成诸如登录跳转、服务端渲染等协作。因此当你把端口从默认值改到4000时若不同步更新WASP_WEB_CLIENT_URL服务端仍会指向旧的客户端地址导致跨端口协作如 OAuth 回调、路由跳转失效。端口改了地址变量必须跟着改二者是一体两面。实战三自定义客户端基础路径base默认情况下客户端应用从站点根路径/提供服务。如果你希望把应用挂载在子路径下例如域名后带/my-app/前缀可以定制 Vite 的base选项JavaScript 项目src/client/vite.config.jsexport default { base: /my-app/, }TypeScript 项目src/client/vite.config.tsimport { defineConfig } from vite export default defineConfig({ base: /my-app/, })设置后打包产物的资源引用路径、dev server 的路由前缀都会以/my-app/为基准。例如应用部署在https://example.com/my-app时页面路由与静态资源JS、CSS、图片都将从https://example.com/my-app下正确加载。更推荐的方式使用 client.baseDir从仓库源码看base在 Wasp 中属于被锁定的强制项当前实现的forcedOptions中base由client.baseDir推导而来。因此在更新的 Wasp 版本中官方推荐直接在 Wasp 配置中声明client.baseDir而不是手写 Vite 的base详见 client-config.mdapp MyApp { title: My app, // ... client: { baseDir: /my-app, } }这会让 Wasp 同时完成两件事把 React Router 的basename设为/my-app并把 Vite 的base设为/my-app从而保证路由与静态资源在子路径下同时正确。⚠️ 与端口类似设置baseDir后必须让WASP_WEB_CLIENT_URL包含该基础路径。例如应用部署在https://example.com/my-app时WASP_WEB_CLIENT_URL应设为https://example.com/my-app而非https://example.com完整说明见 _baseDirEnvNote.md。源码视角Wasp 默认 Vite 配置到底替你做主了什么为了让你在自定义时心里有数这里梳理当前仓库中 Wasp 的 Vite 插件实际强制控制的配置项见 waspConfig.ts 中的forcedOptions配置项内部取值为什么不能自定义base由client.baseDir推导默认为/Wasp 会把 React Router 的basename设为相同值二者必须一致envPrefixREACT_APP_Wasp 的客户端环境变量校验依赖此前缀build.outDir.wasp/out/web-app/build构建产物必须落在 Wasp 部署流程期望的位置server.port动态分配经PORT环境变量注入Wasp 需要管理端口以协调服务端与客户端请用wasp start --client-port控制server.strictPorttrue否则端口被占用时 Vite 会静默换端口服务端将指向错误的 URLpreview.port动态分配与server.port同理对应wasp build start的预览服务器若你在vite.config.ts中显式设置了以上任意一项wasp()插件会抛出错误并要求删除源码中的throwIfOverridingForcedOptions会逐项比对并给出提示文案。除强制项外Wasp 的默认配置还做了这些增值处理同样可在 waspConfig.ts 中看到依赖去重resolve.dedupe对react、react-dom、tanstack/react-query、react-router做单实例去重避免出现 Hook 规则违反、QueryClient 重复实例等运行时错误Prisma 客户端别名resolve.alias把.prisma/client导入重定向到node_modules/.prisma/client保证服务端生成的 Prisma Client 能被客户端正确解析Vitest 测试配置默认注入wasp/client/test/setup作为 setup 文件、默认jsdom环境、排除 Wasp 产物目录依赖预构建排除optimizeDeps.exclude排除 Wasp SDK 与内部 libs避免缓存导致 HMR 失效。Wasp 的 Vite 插件整体由多个子插件组成见 wasp.ts 与生成器 VitePluginG.hswasp:config注入上述强制配置与合并逻辑virtual-user-modules/virtual-wasp-modules提供wasp/...虚拟模块与路由等用户模块wasp:env-file开发阶段加载.env.client并以import.meta.env.*注入见 envFile.tswasp:detect-server-imports拦截并报错客户端代码禁止导入服务端代码见 detectServerImports.tswasp:typescript-check仅在生产构建时执行tsc --noEmit类型检查见 typescriptCheck.tswasp:validate-env构建前起一个临时 Vite server 校验客户端环境变量 schema见 validateEnv.ts最后是vitejs/plugin-react与 SSR 相关插件。理解了这份默认配置清单你就能准确判断哪些改动是安全的增量加插件、改server.open、配代理哪些改动会触发 Wasp 的报错动base、envPrefix、build.outDir、server.port。想查看一份真实的、可运行的成品配置可以参考仓库中的启动器模板 basic/vite.config.ts它演示了wasp()插件与 Tailwind 插件并存的标准写法。版本演进提示0.11.8 与当前仓库的差异本文以0.11.8版本文档为核心该版本的定制方式是直接在src/client/vite.config.{js,ts}里写配置Wasp 自动合并。而当前仓库所对应的较新版本已将这一机制演化为显式的wasp()插件vite.config.ts移至项目根目录且必须把wasp()放在plugins数组第一位其他插件如 Tailwind放在其后import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [wasp()], })新版文档还支持通过wasp()插件的reactOptions参数透传vitejs/plugin-react的选项Babel 插件、Fast Refresh 设置、JSX 配置等并提供了端口改用wasp start --client-port 4000控制的 CLI 方式详见 web/docs/project/custom-vite-config.md。如果你的项目基于较新版本建议以新版文档为准两者在Wasp 锁定关键配置、其余放权这一核心思想上是一脉相承的。常见陷阱与排查清单最后汇总本主题下最易出错的三类问题供你在自定义配置后快速自检改了端口忘了改地址server.port变更后.env.server中的WASP_WEB_CLIENT_URL必须同步指向新端口否则服务端与客户端的协作会失联。动了 Wasp 的强制项base、envPrefix、build.outDir、server.port、server.strictPort、preview.port均被 Wasp 锁定在较新版本中显式设置会直接收到报错此时应改用client.baseDir、wasp start --client-port等官方入口。子路径部署只配了一半设置了base/baseDir却没更新WASP_WEB_CLIENT_URL会出现路由正常但资源 404或反向的情况。务必保证 Vite 的base、React Router 的basename、WASP_WEB_CLIENT_URL三者指向同一路径。遵循增量定制、尊重强制项、联动环境变量这三个原则你就能在 Wasp 的约束框架内自由地为客户端接入插件、调整开发服务器与构建行为同时保持wasp start/wasp build全流程的稳定。【免费下载链接】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），仅供参考