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 引入了两项主要变更变更项影响范围破坏性程度启用 npm workspaces 管理生成的应用依赖安装方式、磁盘占用、package.json结构需手动补键并重建依赖config.allowedCORSOrigins类型从string \| string[]变为(string \| RegExp)[]所有使用 CORS 配置扩展的服务端代码可能引发 TypeScript 类型错误这两项变更分别属于基础设施透明重构与公共 API 类型收紧对开发者的迁移工作量与处理方式完全不同。二、npm workspaces0.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 users 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.X3.1 第一步升级 Wasp 版本打开项目根目录下的 Wasp 文件通常为main.wasp将version字段更新为^0.19.0app 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 变更前后对比版本类型说明0.18.Xstring \| string[]既可以是单个字符串也可以是数组0.19.X(string \| RegExp)[]恒为数组元素可为字符串或正则表达式变更的核心价值在于默认 CORS 规则可以更自然地扩展。由于新类型恒为数组你可以直接通过展开运算符追加额外域而无需处理单值还是数组的分支。4.2 新类型的源码依据从 config.ts 模板 可以看到生成的 SDK 中Config类型的定义allowedCORSOrigins: (string | RegExp)[];其默认值按环境区分config.ts 模板const allowedCORSOriginsPerEnv: RecordNodeEnv, 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.middlewareConfigFnapp 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.rawapi 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 start报workspaces相关错误未在package.json声明 workspaces或值不正确按上文补全workspaces: [.wasp/build/*, .wasp/out/*]后执行wasp clean升级后npm install报依赖冲突旧锁文件残留旧布局删除package-lock.json后重新安装TS 项目报allowedCORSOrigins类型错误旧代码假设其为string \| string[]按新类型(string \| RegExp)[]调整推荐通过middlewareConfigFn扩展生产环境跨域请求失败CORS 默认仅允许前端 origin在中间件中追加合法域名或正则package.json中残留wasp依赖该包已由 workspaces 管理从依赖中移除见 Common.hs 的forbiddenUserDeps七、总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wasp 0.18 到 0.19 迁移指南：npm workspaces 与 CORS 配置类型变更实战解析
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 引入了两项主要变更变更项影响范围破坏性程度启用 npm workspaces 管理生成的应用依赖安装方式、磁盘占用、package.json结构需手动补键并重建依赖config.allowedCORSOrigins类型从string \| string[]变为(string \| RegExp)[]所有使用 CORS 配置扩展的服务端代码可能引发 TypeScript 类型错误这两项变更分别属于基础设施透明重构与公共 API 类型收紧对开发者的迁移工作量与处理方式完全不同。二、npm workspaces0.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 users 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.X3.1 第一步升级 Wasp 版本打开项目根目录下的 Wasp 文件通常为main.wasp将version字段更新为^0.19.0app 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 变更前后对比版本类型说明0.18.Xstring \| string[]既可以是单个字符串也可以是数组0.19.X(string \| RegExp)[]恒为数组元素可为字符串或正则表达式变更的核心价值在于默认 CORS 规则可以更自然地扩展。由于新类型恒为数组你可以直接通过展开运算符追加额外域而无需处理单值还是数组的分支。4.2 新类型的源码依据从 config.ts 模板 可以看到生成的 SDK 中Config类型的定义allowedCORSOrigins: (string | RegExp)[];其默认值按环境区分config.ts 模板const allowedCORSOriginsPerEnv: RecordNodeEnv, 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.middlewareConfigFnapp 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.rawapi 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 start报workspaces相关错误未在package.json声明 workspaces或值不正确按上文补全workspaces: [.wasp/build/*, .wasp/out/*]后执行wasp clean升级后npm install报依赖冲突旧锁文件残留旧布局删除package-lock.json后重新安装TS 项目报allowedCORSOrigins类型错误旧代码假设其为string \| string[]按新类型(string \| RegExp)[]调整推荐通过middlewareConfigFn扩展生产环境跨域请求失败CORS 默认仅允许前端 origin在中间件中追加合法域名或正则package.json中残留wasp依赖该包已由 workspaces 管理从依赖中移除见 Common.hs 的forbiddenUserDeps七、总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考