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),仅供参考

相关新闻

容错量子计算瓶颈:经典处理器如何拖慢量子纠错循环

容错量子计算瓶颈:经典处理器如何拖慢量子纠错循环

1. 这个标题到底在说啥?——先别急着翻论文,听我讲个真实场景“卡住容错量子计算咽喉的,竟然是旁边的经典处理器?”——这句话刚看到时,我也愣了一下。不是说量子计算机自己算不动吗?怎么反而被它边上那个天…

2026/11/7 20:43:29 阅读更多 →
YOLOv5目标检测与训练可视化:Flask+Vue前端集成实现

YOLOv5目标检测与训练可视化:Flask+Vue前端集成实现

简介:这套基于YOLOv5的Vue前端目标检测与训练可视化系统,面向有一定Python和前端基础的开发者,解决目标检测模型训练与结果展示脱节的问题,可应用于安全监控、工业质检、智能交通等场景,提供从数据准备、模型训练到界面…

2026/11/11 3:34:38 阅读更多 →
基于TF-IDF、LDA与DBSCAN的观影用户聚类与电影推荐分析

基于TF-IDF、LDA与DBSCAN的观影用户聚类与电影推荐分析

简介:资源面向电影推荐与文本挖掘方向的毕业设计、课程设计开发者,围绕TF-IDF特征加权、LDA主题建模与DBSCAN密度聚类,形成一套从评论语料处理到用户聚类、电影推荐的可运行方案。压缩包共20个文件,主体为12个Python脚本&#xff…

2026/11/7 3:24:50 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/16 8:22:12 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/16 6:41:34 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/16 8:22:12 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/16 8:22:12 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/16 7:30:18 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/16 8:22:12 阅读更多 →

日新闻

周新闻

月新闻