Wasp 0.17 升级 0.18 迁移指南Node 22.12、Vite 7 与 ESM 化的 Tailwind 配置【免费下载链接】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 官方版本化文档《Migration from 0.17.X to 0.18.X》见 web/versioned_docs/version-0.18/migration-guide.md展开完整覆盖从 0.17.X 升级到 0.18.X 的全部步骤Node.js 运行时的版本门槛、构建工具链 Vite 7 的升级、Tailwind 配置从 CommonJS 到 ESM 的转换以及 Bash 补全机制的简化。读完本文你将能按部就班地把现有 Wasp 应用升级到 0.18并理解这些变更在 Wasp 源码与生成器中的落地方式。0.18.0 带来了什么0.18.0 是一次以底层工具链升级为主基调的版本官方明确表示这些变更对破坏性改动保持克制预期绝大多数甚至全部Wasp 应用无需改动代码即可平滑运行在新版本上。其核心变化集中在以下四个方面。Wasp 现在要求 Node.js 22.12Wasp 将 Node.js 的最低版本要求提升到22.12 或更高。从 Node.js 20 跳到 22 带来了显著的性能提升、新特性例如稳定的fetch、默认启用的require(esm)以及整体安全性的增强。由于这些 Node.js 版本本身破坏性改动很少因此官方预期大多数 Wasp 应用无需修改代码即可直接运行在 Node 22 上。Wasp 内部改用 Vite 7Wasp 将内部构建工具升级到Vite 7带来性能提升与更好的生态兼容性。升级后你可以在自定义 Vite 配置中使用那些依赖 Vite 7 新特性的更新插件。该升级对 Wasp 应用没有已知的破坏性改动官方预期大部分应用可以不改任何代码完成升级。Tailwind 配置转向 ESMWasp 将 Tailwind 相关配置文件从 CommonJSCJS迁移到 ECMAScript ModulesESM影响范围包括import/export 语法与文件扩展名.cjs→.js。这是本次迁移中唯一需要动手改代码的部分具体操作见下文第 3、4 步。Bash 补全设置被简化你不再需要单独生成一个补全文件而是可以直接把补全能力挂到 shell 配置中。同时0.18 为 Bash 补全补充了此前缺失的db系列子命令。从 waspc/cli/src/Wasp/Cli/Command/BashCompletion.hs 的源码可以看到补全逻辑会读取 shell 注入的COMP_LINE环境变量对顶层命令new、version、doctor、completion、start、db、clean、compile、build、deploy、telemetry、deps、dockerfile、show、test、studio等以及db子命令start、reset、seed、migrate-dev、studio做前缀匹配这正是文档中补全了缺失的 db 命令的实现依据。如何迁移从 0.17.X 到 0.18.X 的七个步骤1. 安装 Node.js 22.12 或更高版本首先确认本机 Node 版本满足要求node -v如果你当初是跟随官方 快速开始教程含环境要求一节安装的 Node.js可以直接通过nvm use 22切换版本如果使用其他方式安装请参照对应官方安装文档完成升级。源码侧的依据Wasp 对 Node 版本下限的约束并非只停留在文档层面。在 waspc/src/Wasp/Node/Version.hs 中checkUserNodeVersion checkUserToolVersion node [--version] oldestWaspSupportedNodeVersion会在wasp命令运行时实际调用node --version做版本校验同时waspVersionInterval SV.versionBounds $ SV.backwardsCompatibleWith oldestWaspSupportedNodeVersion定义了向后兼容的版本区间。此外 waspc/src/Wasp/AppSpec/Valid.hs 会对用户在 Wasp 文件中显式声明的 Node 版本范围做合法性校验例如用户指定[22.12, 24)区间时取其下界 22.12而 waspc/src/Wasp/Generator/DockerGenerator.hs 会把getLowestNodeVersionUserAllows的结果写入生成的 Dockerfile保证容器镜像使用的 Node 基础镜像同样不低于该门槛。可以推断Node 版本下限是 Wasp 持续抬升的约束——在本文档对应的 0.18 版本中该下限是 22.12而当前仓库主线源码中oldestWaspSupportedNodeVersion已经进一步提升升级时请始终以你所使用 Wasp 版本的文档为准。2. 修改 Wasp 文件中的版本号打开项目根目录的main.wasp文件把wasp块的version字段更新为^0.18.0app MyApp { wasp: { // highlight-next-line version: ^0.18.0 }, }使用^前缀意味着允许安装 0.18 系列内的最新补丁版本这是 Wasp 官方推荐的写法。3. 将 CJS 语法转换为 ESM把tailwind.config.cjs中的require/module.exports改写为import/export default。注意resolveProjectPath与 Tailwind 插件的导入方式都要同步变化迁移前tailwind.config.cjsconst { resolveProjectPath } require(wasp/dev) /** type {import(tailwindcss).Config} */ module.exports { content: [resolveProjectPath(./src/**/*.{js,jsx,ts,tsx})], theme: { extend: {}, }, plugins: [require(tailwindcss/typography)], };迁移后tailwind.config.jsimport TailwindTypography from tailwindcss/typography; import { resolveProjectPath } from wasp/dev; /** type {import(tailwindcss).Config} */ export default { content: [resolveProjectPath(./src/**/*.{js,jsx,ts,tsx})], theme: { extend: {}, }, plugins: [TailwindTypography], };这里用到的resolveProjectPath来自wasp/dev工具包它负责把相对于项目根的路径解析为绝对路径从而让 Tailwind 的内容扫描范围content准确覆盖src下的源码文件。postcss.config.cjs也需要做同样的转换迁移前postcss.config.cjsmodule.exports { plugins: { tailwindcss: {}, autoprefixer: {}, }, };迁移后postcss.config.jsexport default { plugins: { tailwindcss: {}, autoprefixer: {}, }, };4. 重命名 Tailwind 配置文件并锁定 Tailwind v3将两个配置文件的扩展名从.cjs改为.jstailwind.config.cjs➝tailwind.config.jspostcss.config.cjs➝postcss.config.js同时把 Tailwind 更新到最新的 v3以确保与新 ESM 配置的兼容性npm install -D tailwindcss3需要说明的是文档要求在 0.18 阶段使用 Tailwind v3是因为 ESM 化配置是针对 v3 生态的迁移路径后续版本的 Wasp 已进一步演进例如当前仓库的 basic starter 模板 waspc/data/Cli/starters/basic/package.json 中已使用tailwindcss^4与tailwindcss/vite若你未来升级到更高版本请以对应版本的迁移文档为准。5. 检查与 Vite 7 的兼容性Wasp 0.18 内部使用 Vite 7 以获得更好的性能与稳定性。Vite 7 自带一些破坏性变更但官方预期不会影响 Wasp 应用如果你在应用中直接使用了 Vite 特性建议对照 Vite 官方 v5、v6、v7 各版本的迁移指南逐项排查Vite 自身对这些升级分别给出了官方迁移说明。对绝大多数 Wasp 应用而言唯一需要手动修改的是package.json中的 Vite 依赖版本迁移前{ // ... devDependencies: { // ... vite: ^4.3.9 } }迁移后{ // ... devDependencies: { // ... vite: ^7.0.6 } }把vite从^4.3.9直接抬升到^7.0.6后续由npm install完成实际安装。从仓库的 starter 模板演进waspc/data/Cli/starters/basic/package.json 当前主线已使用vite: ^8.1.0可以看出Wasp 对构建工具的升级是持续进行的0.18 是其中切到 Vite 7的关键节点。6. 更新 Bash 补全如果你之前使用过0.18 简化了 Bash 补全的工作方式不再需要维护一个独立的补全文件只需在 shell 配置中加一行即可启用补全。更新分两步第一步删除旧的wasp-completion文件。旧版本要求你通过如下命令生成补全文件文件位置自选wasp completion:generate your-chosen-directory/wasp-completion该文件在 0.18 中已不再需要可以直接删除。第二步更新 shell 配置。旧方式是 source 补全文件新方式改为直接调用complete内置命令迁移前source your-chosen-directory/wasp-completion迁移后complete -o default -o nospace -C wasp completion:list wasp源码侧的依据这一行配置的完整使用说明在 Wasp CLI 源码 waspc/cli/src/Wasp/Cli/Command/BashCompletion.hs 的printBashCompletionInstruction函数中有更详细的指引值得对照参考将该行追加到 shell 配置文件的末尾默认位置为 Bash 的~/.bashrc或 Zsh 的~/.zshrcZsh 用户注意complete是 Bash 的内置命令Zsh 需要先启用 Bash 补全兼容层在上一行之前追加autoload -Uz X bashcompinit bashcompinit使用 Oh My Zsh 等框架时该兼容层默认已开启可跳过此步保存文件后重启终端即可用 TAB 键自动补全 Wasp 命令。补全实现本身位于bashCompletion函数它读取 Bash 通过COMP_LINE环境变量传入的当前输入行去掉程序名后按顶层命令 /db子命令 /show子命令分层做前缀匹配并输出候选命令列表——这正是wasp completion:list的行为。7. 完成享受升级后的 Wasp 应用完成以上六步后你的 Wasp 应用就已迁移到 0.18。整个过程的关键动作可以浓缩为一张清单步骤动作关键命令 / 改动1升级 Node.jsnode -v确认版本 ≥ 22.12nvm use 222升级 Wasp 版本main.wasp中version: ^0.18.03CJS → ESM改写tailwind.config.cjs、postcss.config.cjs为import/export default4重命名配置文件.cjs→.jsnpm install -D tailwindcss35升级 Vitepackage.json中vite: ^7.0.66简化 Bash 补全删除补全文件改用complete -o default -o nospace -C wasp completion:list wasp7验证运行wasp start确认应用正常启动迁移要点小结本次升级以工具链为主代码改动极少Node.js 20 → 22、构建器升级到 Vite 7 均被官方评估为无已知破坏性变更唯一需要动代码的是 Tailwind/PostCSS 配置的 ESM 化与文件重命名。版本下限由 CLI 实际强制执行wasp命令运行时会对node --version结果与支持的下限做校验见 waspc/src/Wasp/Node/Version.hs生成 Docker 镜像时也会把同样的版本下限写入 Dockerfile见 waspc/src/Wasp/Generator/DockerGenerator.hs因此不要跳过第 1 步。补全机制已内置0.18 起补全不再是生成文件 source的模式而是通过wasp completion:list命令配合 Bashcomplete内置命令动态完成db系列子命令也已纳入补全范围。版本演进是持续的当前仓库主线已进一步升级 Node 下限、Vite 与 Tailwind 版本本文档严格对应 0.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），仅供参考 
长河君 · 2026/9/15 16:01:02 · 阅读 1.2k Wasp 0.17 升级 0.18 迁移指南：Node 22.12、Vite 7 与 ESM 化的 Tailwind 配置
Wasp 0.17 升级 0.18 迁移指南Node 22.12、Vite 7 与 ESM 化的 Tailwind 配置【免费下载链接】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 官方版本化文档《Migration from 0.17.X to 0.18.X》见 web/versioned_docs/version-0.18/migration-guide.md展开完整覆盖从 0.17.X 升级到 0.18.X 的全部步骤Node.js 运行时的版本门槛、构建工具链 Vite 7 的升级、Tailwind 配置从 CommonJS 到 ESM 的转换以及 Bash 补全机制的简化。读完本文你将能按部就班地把现有 Wasp 应用升级到 0.18并理解这些变更在 Wasp 源码与生成器中的落地方式。0.18.0 带来了什么0.18.0 是一次以底层工具链升级为主基调的版本官方明确表示这些变更对破坏性改动保持克制预期绝大多数甚至全部Wasp 应用无需改动代码即可平滑运行在新版本上。其核心变化集中在以下四个方面。Wasp 现在要求 Node.js 22.12Wasp 将 Node.js 的最低版本要求提升到22.12 或更高。从 Node.js 20 跳到 22 带来了显著的性能提升、新特性例如稳定的fetch、默认启用的require(esm)以及整体安全性的增强。由于这些 Node.js 版本本身破坏性改动很少因此官方预期大多数 Wasp 应用无需修改代码即可直接运行在 Node 22 上。Wasp 内部改用 Vite 7Wasp 将内部构建工具升级到Vite 7带来性能提升与更好的生态兼容性。升级后你可以在自定义 Vite 配置中使用那些依赖 Vite 7 新特性的更新插件。该升级对 Wasp 应用没有已知的破坏性改动官方预期大部分应用可以不改任何代码完成升级。Tailwind 配置转向 ESMWasp 将 Tailwind 相关配置文件从 CommonJSCJS迁移到 ECMAScript ModulesESM影响范围包括import/export 语法与文件扩展名.cjs→.js。这是本次迁移中唯一需要动手改代码的部分具体操作见下文第 3、4 步。Bash 补全设置被简化你不再需要单独生成一个补全文件而是可以直接把补全能力挂到 shell 配置中。同时0.18 为 Bash 补全补充了此前缺失的db系列子命令。从 waspc/cli/src/Wasp/Cli/Command/BashCompletion.hs 的源码可以看到补全逻辑会读取 shell 注入的COMP_LINE环境变量对顶层命令new、version、doctor、completion、start、db、clean、compile、build、deploy、telemetry、deps、dockerfile、show、test、studio等以及db子命令start、reset、seed、migrate-dev、studio做前缀匹配这正是文档中补全了缺失的 db 命令的实现依据。如何迁移从 0.17.X 到 0.18.X 的七个步骤1. 安装 Node.js 22.12 或更高版本首先确认本机 Node 版本满足要求node -v如果你当初是跟随官方 快速开始教程含环境要求一节安装的 Node.js可以直接通过nvm use 22切换版本如果使用其他方式安装请参照对应官方安装文档完成升级。源码侧的依据Wasp 对 Node 版本下限的约束并非只停留在文档层面。在 waspc/src/Wasp/Node/Version.hs 中checkUserNodeVersion checkUserToolVersion node [--version] oldestWaspSupportedNodeVersion会在wasp命令运行时实际调用node --version做版本校验同时waspVersionInterval SV.versionBounds $ SV.backwardsCompatibleWith oldestWaspSupportedNodeVersion定义了向后兼容的版本区间。此外 waspc/src/Wasp/AppSpec/Valid.hs 会对用户在 Wasp 文件中显式声明的 Node 版本范围做合法性校验例如用户指定[22.12, 24)区间时取其下界 22.12而 waspc/src/Wasp/Generator/DockerGenerator.hs 会把getLowestNodeVersionUserAllows的结果写入生成的 Dockerfile保证容器镜像使用的 Node 基础镜像同样不低于该门槛。可以推断Node 版本下限是 Wasp 持续抬升的约束——在本文档对应的 0.18 版本中该下限是 22.12而当前仓库主线源码中oldestWaspSupportedNodeVersion已经进一步提升升级时请始终以你所使用 Wasp 版本的文档为准。2. 修改 Wasp 文件中的版本号打开项目根目录的main.wasp文件把wasp块的version字段更新为^0.18.0app MyApp { wasp: { // highlight-next-line version: ^0.18.0 }, }使用^前缀意味着允许安装 0.18 系列内的最新补丁版本这是 Wasp 官方推荐的写法。3. 将 CJS 语法转换为 ESM把tailwind.config.cjs中的require/module.exports改写为import/export default。注意resolveProjectPath与 Tailwind 插件的导入方式都要同步变化迁移前tailwind.config.cjsconst { resolveProjectPath } require(wasp/dev) /** type {import(tailwindcss).Config} */ module.exports { content: [resolveProjectPath(./src/**/*.{js,jsx,ts,tsx})], theme: { extend: {}, }, plugins: [require(tailwindcss/typography)], };迁移后tailwind.config.jsimport TailwindTypography from tailwindcss/typography; import { resolveProjectPath } from wasp/dev; /** type {import(tailwindcss).Config} */ export default { content: [resolveProjectPath(./src/**/*.{js,jsx,ts,tsx})], theme: { extend: {}, }, plugins: [TailwindTypography], };这里用到的resolveProjectPath来自wasp/dev工具包它负责把相对于项目根的路径解析为绝对路径从而让 Tailwind 的内容扫描范围content准确覆盖src下的源码文件。postcss.config.cjs也需要做同样的转换迁移前postcss.config.cjsmodule.exports { plugins: { tailwindcss: {}, autoprefixer: {}, }, };迁移后postcss.config.jsexport default { plugins: { tailwindcss: {}, autoprefixer: {}, }, };4. 重命名 Tailwind 配置文件并锁定 Tailwind v3将两个配置文件的扩展名从.cjs改为.jstailwind.config.cjs➝tailwind.config.jspostcss.config.cjs➝postcss.config.js同时把 Tailwind 更新到最新的 v3以确保与新 ESM 配置的兼容性npm install -D tailwindcss3需要说明的是文档要求在 0.18 阶段使用 Tailwind v3是因为 ESM 化配置是针对 v3 生态的迁移路径后续版本的 Wasp 已进一步演进例如当前仓库的 basic starter 模板 waspc/data/Cli/starters/basic/package.json 中已使用tailwindcss^4与tailwindcss/vite若你未来升级到更高版本请以对应版本的迁移文档为准。5. 检查与 Vite 7 的兼容性Wasp 0.18 内部使用 Vite 7 以获得更好的性能与稳定性。Vite 7 自带一些破坏性变更但官方预期不会影响 Wasp 应用如果你在应用中直接使用了 Vite 特性建议对照 Vite 官方 v5、v6、v7 各版本的迁移指南逐项排查Vite 自身对这些升级分别给出了官方迁移说明。对绝大多数 Wasp 应用而言唯一需要手动修改的是package.json中的 Vite 依赖版本迁移前{ // ... devDependencies: { // ... vite: ^4.3.9 } }迁移后{ // ... devDependencies: { // ... vite: ^7.0.6 } }把vite从^4.3.9直接抬升到^7.0.6后续由npm install完成实际安装。从仓库的 starter 模板演进waspc/data/Cli/starters/basic/package.json 当前主线已使用vite: ^8.1.0可以看出Wasp 对构建工具的升级是持续进行的0.18 是其中切到 Vite 7的关键节点。6. 更新 Bash 补全如果你之前使用过0.18 简化了 Bash 补全的工作方式不再需要维护一个独立的补全文件只需在 shell 配置中加一行即可启用补全。更新分两步第一步删除旧的wasp-completion文件。旧版本要求你通过如下命令生成补全文件文件位置自选wasp completion:generate your-chosen-directory/wasp-completion该文件在 0.18 中已不再需要可以直接删除。第二步更新 shell 配置。旧方式是 source 补全文件新方式改为直接调用complete内置命令迁移前source your-chosen-directory/wasp-completion迁移后complete -o default -o nospace -C wasp completion:list wasp源码侧的依据这一行配置的完整使用说明在 Wasp CLI 源码 waspc/cli/src/Wasp/Cli/Command/BashCompletion.hs 的printBashCompletionInstruction函数中有更详细的指引值得对照参考将该行追加到 shell 配置文件的末尾默认位置为 Bash 的~/.bashrc或 Zsh 的~/.zshrcZsh 用户注意complete是 Bash 的内置命令Zsh 需要先启用 Bash 补全兼容层在上一行之前追加autoload -Uz X bashcompinit bashcompinit使用 Oh My Zsh 等框架时该兼容层默认已开启可跳过此步保存文件后重启终端即可用 TAB 键自动补全 Wasp 命令。补全实现本身位于bashCompletion函数它读取 Bash 通过COMP_LINE环境变量传入的当前输入行去掉程序名后按顶层命令 /db子命令 /show子命令分层做前缀匹配并输出候选命令列表——这正是wasp completion:list的行为。7. 完成享受升级后的 Wasp 应用完成以上六步后你的 Wasp 应用就已迁移到 0.18。整个过程的关键动作可以浓缩为一张清单步骤动作关键命令 / 改动1升级 Node.jsnode -v确认版本 ≥ 22.12nvm use 222升级 Wasp 版本main.wasp中version: ^0.18.03CJS → ESM改写tailwind.config.cjs、postcss.config.cjs为import/export default4重命名配置文件.cjs→.jsnpm install -D tailwindcss35升级 Vitepackage.json中vite: ^7.0.66简化 Bash 补全删除补全文件改用complete -o default -o nospace -C wasp completion:list wasp7验证运行wasp start确认应用正常启动迁移要点小结本次升级以工具链为主代码改动极少Node.js 20 → 22、构建器升级到 Vite 7 均被官方评估为无已知破坏性变更唯一需要动代码的是 Tailwind/PostCSS 配置的 ESM 化与文件重命名。版本下限由 CLI 实际强制执行wasp命令运行时会对node --version结果与支持的下限做校验见 waspc/src/Wasp/Node/Version.hs生成 Docker 镜像时也会把同样的版本下限写入 Dockerfile见 waspc/src/Wasp/Generator/DockerGenerator.hs因此不要跳过第 1 步。补全机制已内置0.18 起补全不再是生成文件 source的模式而是通过wasp completion:list命令配合 Bashcomplete内置命令动态完成db系列子命令也已纳入补全范围。版本演进是持续的当前仓库主线已进一步升级 Node 下限、Vite 与 Tailwind 版本本文档严格对应 0.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），仅供参考