企业官网建设流程全解析

Wasp 0.18 到 0.19 迁移指南：npm workspaces 与 CORS 配置类型变更实战解析

【免费下载链接】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 0.19.0 版本迁移为核心，系统梳理从 0.18.X 升级到 0.19.X 的全部操作步骤，涵盖 npm workspaces 依赖管理重构、config.allowedCORSOrigins类型变更两大破坏性变更，以及迁移后验证与常见问题排查。结合 NpmWorkspaces.hs、config.ts 模板、globalMiddleware.ts 等源码，深入解释变更背后的设计动机与底层实现。读完本文，你将能独立完成一次干净的 Wasp 0.19 升级，并掌握新版 CORS 配置的正确写法。

一、0.19.0 版本变更总览

Wasp 0.19.0 引入了两项主要变更：

这两项变更分别属于"基础设施透明重构"与"公共 API 类型收紧"，对开发者的迁移工作量与处理方式完全不同。

二、npm workspaces：0.19 依赖管理的底层重构

2.1 变更动机

Wasp 0.19 开始使用 npm workspaces 来管理生成的应用程序。这是一次基础架构层面的重构，目标是：

• 依赖系统更可靠：用户项目、生成的 server 与 web 应用、以及 Wasp SDK 三部分依赖统一由顶层npm install一次覆盖；
• 为未来特性做准备：workspace 化让后续功能（如 SDK 分发、子包发布）有了更灵活的载体；
• 安装更快、磁盘占用更小：依赖提升（hoisting）到顶层，避免重复安装。

从源码看，NpmWorkspaces.hs 中requiredWorkspaceGlobs定义了必须写入用户package.json的两个 workspace glob，它们分别指向：

• .wasp/build/*—— 生成的应用代码目录（server 与 web 应用所在位置）；
• .wasp/out/*所对应的 SDK 目录（源码中通过dotWaspDirInWaspProjectDir </> generatedAppDirInDotWaspDir </> sdkRootDirInGeneratedAppDir计算得出）。

同时 NpmInstall.hs 的注释明确说明："Thanks to npm workspaces, this single install covers the user's project deps, the generated server and web app deps, and the Wasp SDK."——单次安装即可覆盖三部分依赖。

此外，Workspaces.hs 还内置了一个校验器：workspaces字段缺失或值不正确时，生成器会报错并要求其值为指定数组。而 Common.hs 中的forbiddenUserDeps将wasp包列入禁止用户声明的依赖名单，理由是它由workspaces字段管理，不应被用户显式依赖覆盖——这也是升级时必须先检查package.json中是否有wasp依赖的原因。

2.2 对日常开发的透明性

npm workspaces 的引入对开发流程基本透明：你依然使用wasp start启动开发环境，wasp build构建生产版本。变化主要体现在工程文件层面：

• 顶层package.json新增workspaces字段；
• node_modules结构变为 workspace 提升布局；
• npm install一次覆盖用户项目、生成代码与 SDK 的依赖。

2.3 Wasp 校验器的强制约束

迁移指南要求你"添加workspaces键"，这并非可选项。从 Workspaces.hs 的校验逻辑可以推断：当workspaces缺失或值不正确时，wasp start/wasp build会直接失败并提示错误信息。正确值必须是：

"workspaces": [".wasp/build/*", ".wasp/out/*"]

三、逐步迁移：从 0.18.X 升级到 0.19.X

3.1 第一步：升级 Wasp 版本

打开项目根目录下的 Wasp 文件（通常为main.wasp），将version字段更新为^0.19.0：

app MyApp { wasp: { version: "^0.19.0" }, }

^前缀表示允许安装 0.19.x 范围内的最新补丁版本。升级后建议先运行一次wasp version确认 CLI 版本已切换到 0.19 系列。

3.2 第二步：在 package.json 中声明 workspaces

在项目根目录的package.json中添加workspaces键：

{ "workspaces": [".wasp/build/*", ".wasp/out/*"] }

添加完成后，执行以下命令重建依赖：

wasp clean rm package-lock.json wasp ts-setup # 仅当使用 Wasp TS Config 时需要

逐条说明：

• wasp clean：清除.wasp目录中的生成产物，避免旧布局残留影响新 workspace 结构；
• rm package-lock.json：删除旧的锁文件，让 npm 基于新的 workspace 布局重新解析依赖树；
• wasp ts-setup：仅对启用 TypeScript 的项目（即使用 Wasp TS Config 的项目）执行，用于重新生成与 TS 相关的配置（如tsconfig、SDK 类型）。纯 JS 项目可跳过。

:::noterm package-lock.json会删除本地锁文件，需要npm install（或wasp内部触发）重新生成。请确保团队内同步执行该操作，避免锁文件内容不一致。 :::

3.3 第三步：修复 allowedCORSOrigins 类型错误

在整个代码库中搜索allowedCORSOrigins，定位所有使用点，并修复因类型变化导致的错误。搜索无结果则说明你未使用该特性，无需处理。

官方推荐的 CORS 扩展方式是中间件配置，完整指南见 middleware-config.md。

3.4 第四步：验证升级结果

• 运行wasp start，确认开发服务器正常启动、前端能正常访问后端；
• 运行wasp build，确认生产构建通过、无 TS 类型错误；
• 运行wasp db migrate-dev（如使用数据库），确认迁移正常。

四、allowedCORSOrigins 类型变更详解

4.1 变更前后对比

变更的核心价值在于：默认 CORS 规则可以更自然地扩展。由于新类型恒为数组，你可以直接通过展开运算符追加额外域，而无需处理"单值还是数组"的分支。

4.2 新类型的源码依据

从 config.ts 模板 可以看到，生成的 SDK 中Config类型的定义：

allowedCORSOrigins: (string | RegExp)[];

其默认值按环境区分（config.ts 模板）：

const allowedCORSOriginsPerEnv: Record<NodeEnv, Config['allowedCORSOrigins']> = { development: [/.*/], // 开发环境允许任意来源 production: [getOrigin(frontendUrl)] // 生产环境仅允许前端域名 } const allowedCORSOrigins = allowedCORSOriginsPerEnv[env.NODE_ENV]

即：开发环境默认放行所有来源（/.*/），生产环境默认仅放行前端 URL 的 origin。你可以在自定义中间件中追加条目，例如：

import cors from 'cors' import { config } from 'wasp/server' export const serverMiddlewareFn = (middlewareConfig) => { middlewareConfig.set('cors', cors({ origin: [...config.allowedCORSOrigins, 'https://example1.com', 'https://example2.com'] })) return middlewareConfig }

4.3 CORS 中间件的默认装配

Wasp 的 Express 服务器在 globalMiddleware.ts 中默认装配了六种中间件：

const defaultGlobalMiddlewareConfig: MiddlewareConfig = new Map([ ['helmet', helmet()], ['cors', cors({ origin: config.allowedCORSOrigins })], ['logger', logger('dev')], ['express.json', express.json()], ['express.urlencoded', express.urlencoded()], ['cookieParser', cookieParser()] ])

可见cors中间件的origin选项直接取自config.allowedCORSOrigins，因此该配置类型的变更直接影响全局 CORS 行为。在 0.19 中，由于元素允许RegExp，你可以在生产环境用正则匹配一组相关域名（如子域），而不必逐一枚举。

五、迁移后的中间件配置：三种扩展层次

迁移指南指向的 middleware-config.md 提供了三档自定义中间件的方案，建议按需选用：

5.1 全局中间件（影响所有 Operation 与 API）

在main.wasp中声明server.middlewareConfigFn：

app todoApp { server: { middlewareConfigFn: import { serverMiddlewareFn } from "@src/serverSetup" }, }

在src/serverSetup.ts中通过middlewareConfig.set(...)覆盖或新增全局中间件（如追加 CORS 域、替换默认 CORS 规则）。全局修改会影响所有query、action和api，务必谨慎。

5.2 单 API 中间件

对某个api单独声明middlewareConfigFn，例如为 webhook 回调替换express.json为express.raw：

api webhookCallback { fn: import { webhookCallback } from "@src/apis", middlewareConfigFn: import { webhookCallbackMiddlewareFn } from "@src/apis", httpRoute: (POST, "/webhook/callback"), auth: false }

5.3 路径级中间件（apiNamespace）

对同一路径下的全部 API 路由统一应用中间件：

apiNamespace fooBar { middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis", path: "/foo/bar" }

从实现上看，单 API 中间件以router.post(path, middleware, handler)方式按方法安装，而路径级中间件以router.use(path, middleware)方式挂在路由层，二者覆盖范围不同。

六、常见问题与排查建议

七、总结

Wasp 0.19.0 的迁移核心是三件事：升级版本号、补全 workspaces 配置并重建依赖、按新类型修正 CORS 配置。npm workspaces 让依赖管理更可靠、安装更快、磁盘占用更小，而allowedCORSOrigins的数组化与正则支持让 CORS 扩展更简单灵活。完成上述步骤后，你的应用即可正常运行在 0.19 之上，并享受后续版本迭代带来的新特性。

【免费下载链接】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