企业官网建设流程全解析

Wasp 自定义 Vite 配置完全指南：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

Wasp 使用 Vite 承载客户端的开发服务器与生产构建，本文基于 Wasp 0.18 版官方文档 web/versioned_docs/version-0.18/project/custom-vite-config.md，系统讲解如何通过项目根目录的vite.config.{js,ts}自定义 Vite 配置。读完本文，你将掌握wasp/client/vite插件的正确用法、Wasp 强制保护的核心选项，以及调整开发服务器行为、端口与部署路径的完整实战方案。

Wasp 与 Vite：客户端构建的基石

Wasp 生成的客户端是一个标准的 Vite + React 应用：开发阶段由 Vite 提供热更新（HMR）服务，生产阶段由 Vite 完成打包与静态资源产出。因此，Wasp 将vite.config.{js,ts}直接暴露给开发者，放在项目根目录，作为自定义的切入点。

在 Wasp 0.18 中，这份配置文件已经存在但不"被 Wasp 管理"，它完全由你掌控。不过这份"自由"是有前提的——你必须在配置中导入并使用wasp/client/vite提供的wasp()插件，该插件承载了 Wasp 全栈应用正常运行所需的一切关键能力：

• 全栈应用正常运行所必需的 Vite 配置；
• 环境变量校验；
• 禁止在客户端代码中导入服务端模块；
• 生产构建时的 TypeScript 类型检查。

插件最终会把你的配置与 Wasp 内置默认配置做合并（merge）：原始值以 Wasp 侧为准，数组类配置则做拼接，这保证了用户自定义与框架默认值可以共存。

最小可用配置：wasp() 插件是唯一硬性要求

下面是 Wasp 0.18 的最简合法配置，插件数组中的唯一成员就是wasp()：

import { wasp } from 'wasp/client/vite' import { defineConfig } from 'vite' export default defineConfig({ plugins: [wasp()], })

import { wasp } from 'wasp/client/vite' import { defineConfig } from 'vite' export default defineConfig({ plugins: [wasp()], })

:::warning 插件顺序是硬约束wasp()插件必须位于plugins数组的第一个位置，其余插件（如 Tailwind CSS）必须排在其后。 :::

这一点在仓库中得到了直接印证：Wasp 官方 starter 与示例项目均严格遵循该顺序。例如 waspc/data/Cli/starters/basic/vite.config.ts 中wasp()在前、tailwindcss()在后；examples/kitchen-sink/vite.config.ts 同样如此，并且它还额外演示了如何在自定义配置中扩展test选项（排除 e2e 测试目录）——这说明自定义配置不会破坏 Wasp 的默认能力，只是在其之上叠加。

强制选项：这些值由 Wasp 锁定，不可覆盖

wasp()插件的底层实现（见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts）定义了一组forcedOptions。如果你在自己的vite.config.{js,ts}中显式设置了其中任意一项且与 Wasp 期望值不同，插件会在启动时抛出错误并提示你移除这些配置。完整清单如下：

从源码实现看，强制逻辑非常清晰：throwIfOverridingForcedOptions会遍历上述选项，通过getByPath读取用户配置中的对应路径，一旦发现冲突就抛出包含修改建议的错误信息。例如把base设为/my-app/会得到提示"要从子目录提供服务，请在 Wasp 配置中设置client.baseDir"；设置server.port会被提示改用wasp start --client-port。这种做法避免了用户与框架配置互相覆盖导致的全栈通信错乱。

插件选项：reactOptions 透传

wasp()插件还接受一个可选的reactOptions参数，用于透传底层@vitejs/plugin-react的配置——包括 Babel 插件、Fast Refresh 设置与 JSX 相关配置：

import { wasp } from 'wasp/client/vite' import { defineConfig } from 'vite' export default defineConfig({ plugins: [ wasp({ reactOptions: { // 这里可以传任意 @vitejs/plugin-react 的选项 }, }), ], })

实战一：控制开发服务器是否自动打开浏览器

wasp start默认会自动唤起浏览器。通过自定义server.open选项可以控制这一行为：

export default { server: { open: false, }, }

import { defineConfig } from 'vite' export default defineConfig({ server: { open: false, }, })

注意：server.open不在强制选项之列，你可以自由配置；但server.port、server.strictPort属于受保护项，直接设置会报错（详见上表）。

实战二：自定义开发服务器端口

在 Wasp 0.18 中，控制开发端口不再需要直接修改 Vite 配置，官方推荐使用 CLI 参数。wasp start默认从 3000 起自动挑选第一个可用端口，指定端口则使用：

wasp start --client-port 4000

同样，wasp build start运行的 preview 服务器使用：

wasp build start --client-port 4000

这是因为server.port与preview.port都由 Wasp 动态分配（源码中通过envVarAsNumber从环境变量读取端口值），直接写死在 Vite 配置里会被强制选项检查拦截。

实战三：修改部署基础路径（base path）

如果你希望客户端从/之外的路径提供服务，Wasp 0.18 的正确做法同样是走受支持的配置入口，而非直接改base（它属于强制选项）。在main.wasp.ts中通过client.baseDir声明：

import { app } from "@wasp.sh/spec" export default app({ name: "MyApp", client: { baseDir: "/my-app", }, // ... })

这样当应用部署在https://example.com/my-app时，React Router 能正确解析路由，所有静态资源也会从https://example.com/my-app加载。Wasp 会将该值同步写入 Vite 的base配置（见 web/docs/project/client-config.md）。

:::caution 配套环境变量 设置baseDir后，务必同步更新WASP_WEB_CLIENT_URL环境变量，让它也包含该基础目录。例如应用托管在https://example.com/my-app，则该变量应设为https://example.com/my-app而非https://example.com（详见 web/docs/project/_baseDirEnvNote.md）。 :::

扩展：添加自定义 Vite 插件

wasp()之后可以自由追加第三方插件。以厨房水槽示例 examples/kitchen-sink/vite.config.ts 为蓝本，常见组合如下：

import tailwindcss from '@tailwindcss/vite' import { defineConfig } from 'vite' import { wasp } from 'wasp/client/vite' export default defineConfig({ plugins: [wasp(), tailwindcss()], })

官方 starter waspc/data/Cli/starters/basic/vite.config.ts 使用的正是这一组合。除插件外，你还可以自由调整server的其余行为、build的压缩与分包策略、resolve.alias等 Vite 原生能力——只要不触碰上表中的强制选项即可。

小结

Wasp 0.18 的 Vite 定制模型可以概括为三点：wasp()插件必须第一个加载、六个关键选项被框架锁定（通过client.baseDir与--client-port等受支持入口控制）、其余配置自由合并。理解wasp()插件背后的强制选项检查机制（waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts），你就能在安全边界内充分定制开发与构建流程，而不会破坏 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