Wasp 安装方式迁移实战从脚本安装器到 npm 全局包migrate-to-npm【免费下载链接】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/waspWasp 自 0.21 版本起将安装方式从传统的 curl 脚本安装器切换为 npm 全局包wasp.sh/wasp-cli旧安装器已进入遗留legacy状态。本文以 Wasp 文档中的「Legacy installer migration」公告为核心完整讲清如何用官方的migrate-to-npm迁移工具完成切换、切换后如何通过 npm 安装指定版本以及回退、排错等操作并结合仓库中的 npm 包模板源码解析冲突检测与版本校验的底层机制帮助你在工作站和 CI 环境中安全完成安装方式迁移。为什么要迁移npm 成为唯一受支持的安装方式当前仓库文档中的迁移公告web/docs/_legacy_installer_migration.md明确宣告Wasp 现在作为全局 npm 包安装取代旧的自定义脚本安装器。公告以 Docusaurus:::important提示框形式展示核心信息只有一条命令curl -sSL https://get.wasp.sh/installer.sh | sh -s -- migrate-to-npm公告同时指向详细的遗留安装器指南web/docs/guides/legacy/installer.md该指南给出了更完整的背景从 Wasp 0.21 开始安装统一通过 npm 完成脚本安装器被视为 legacy不再受支持官方只会在可预见的一段时间内保留它以便用户过渡在未迁移到 npm 安装方式之前你将无法获得更新的 Wasp 版本——这是迁移的硬性动机。换言之脚本安装器仍可用但它是一条「只减不增」的死胡同留在旧安装器上就停留在 0.20 时代的能力集里。迁移步骤migrate-to-npm 与 npm 安装官方迁移路径分两步第一步运行迁移工具。迁移工具本身仍挂在旧的installer.sh入口上通过migrate-to-npm子命令触发curl -sSL https://get.wasp.sh/installer.sh | sh -s -- migrate-to-npm第二步改用 npm 安装 Wasp。迁移完成后按常规安装说明通过 npm 安装最新版npm i -g wasp.sh/wasp-clilatest也可以安装指定版本。需要注意的版本边界是0.20.2 及以上的 Wasp 版本已发布到 npm0.20.2 之前的版本只能走旧安装器# Set x.y.z to the version you want to install, e.g. 0.20.2 npm i -g wasp.sh/wasp-clix.y.z底层机制一npm 包的冲突检测与 .uses-npm 标记迁移不是「换个下载渠道」那么简单两种安装方式会向系统写入相同的可执行入口因此必须防止冲突。仓库中的 npm 包模板scripts/make-npm-packages/templates/main-package/揭示了其防护逻辑。主包的 package.json 声明了两个生命周期钩子bin: { wasp: bin.js }, scripts: { postinstall: node postinstall.js, preinstall: node preinstall.js }其中 preinstall.js 在npm i之前执行冲突检测核心逻辑是探测遗留安装检查~/.local/share/wasp-lang目录下是否存在子目录。脚本安装器会把各版本 Wasp 安装为该目录下的子目录因此「目录存在且有子目录」即被判定为脚本安装器安装const WASP_LANG_DIR path.join(os.homedir(), .local, share, wasp-lang); const NPM_MARKER_FILE path.join(WASP_LANG_DIR, .uses-npm);判定冲突若检测到遗留安装、且系统上没有.uses-npm标记文件则报错并以非零码退出提示你先运行migrate-to-npmError: Detected an existing legacy Wasp installation. ... To migrate, run: curl -sSL https://get.wasp.sh/installer.sh | sh -s -- migrate-to-npm写入标记无冲突时创建空标记文件~/.local/share/wasp-lang/.uses-npm等价于touch已存在则不改动内容。该标记即「本系统使用 npm 方式安装 Wasp」的凭证——这正是旧安装器拒绝运行的依据之一也是后文「切回旧安装器」步骤中需要手动删除的文件。这三处路径.local/share/wasp-lang、.local/bin/wasp在 CLI 的 Haskell 源码中同样有定义waspc/cli/src/Wasp/Cli/FileSystem.hs 中甚至用注释声明了三方npm preinstall.js、installer.sh、wasp CLI 本体需保持路径一致说明 npm 包与 CLI 对安装目录的假设是强耦合的这也解释了为什么冲突检测必须存在。底层机制二bin.js 如何按平台分发可执行文件安装到 npm 包后wasp命令实际执行的是 Node 写的包装器 bin.js。从源码结构看它的工作流程是读取构建期生成的data.json中的子包清单按process.platform/process.arch选择子包在 Linux 上还会通过 Node 的 process report 区分 glibc 与 muslbin.js#L52-L64const libc platform linux ? isGlibc() ? glibc : musl : unknown; const selectedSubPackage data.subPackages[platform]?.[arch]?.[libc];找不到匹配子包时抛出Wasp is not supported on this platform.通过execFileSync同步执行真正的 Wasp 二进制并用waspc_datadir环境变量指向数据目录bin.js#L105-L108同时透传process.argv.slice(2)全部命令行参数子进程的退出码被原样冒泡为包装器退出码Node 版本兜底校验子包在 npm 中是optionalDependenciesNode 版本不满足时 npm 不会安装它们且未必报错。因此包装器在导入失败时会主动比对package.json的engines.node与当前 Node 版本不满足则抛出明确的升级提示bin.js#L129-L156。当前模板声明的最低版本为Node.js 24.14.1见 package.json 的engines字段这是使用当前 npm 安装方式的前提。此外主包的 postinstall.js 会在安装后发送一条安装遥测事件PostHog带 500ms 超时可被WASP_TELEMETRY_DISABLE环境变量关闭并在 CI 环境变量如GITHUB_ACTIONS、CI等存在时标记 CI 上下文。过渡期继续暂时使用旧安装器如果还没有完成迁移遗留安装器仍可安装指定版本但必须显式传入版本号不带版本参数时安装器会拒绝运行# Set x.y.z to the version you want to install, e.g. 0.20.1 # The installer will refuse to run without a specific version argument curl -sSL https://get.wasp.sh/installer.sh | sh -s -- -v x.y.z文档明确建议旧安装器只应作为「迁移工作站和 CI 到 npm 安装期间」的临时手段因为它可能与新方式产生冲突。具体来说以下四种情况下旧安装器会打印错误并直接退出、不安装任何东西你已经通过 npm 安装了 Wasp你已经运行过迁移工具即系统上已存在.uses-npm标记你试图安装 Wasp 0.21你调用安装器时没有带版本参数。这四条限制与前文源码完全对应前两条正是preinstall.js中「npm 安装存在 / 标记存在」两种状态的镜像第三条对应 npm 版本线0.20.2 起与脚本安装器版本线的分叉。常见问题与排错1. 需要使用 0.20.2 之前的版本这些版本非常陈旧官方不建议继续使用应尽快升级项目以获得安全与稳定性。在过渡期内仍需继续暂时使用旧安装器 来安装这些旧版本。2. 如何手动切回旧安装器如果已经切到 npm 安装但确需切回例如在 npm 版中遇到了 bug 或工作流缺口——此时建议向官方渠道反馈问题按以下步骤操作卸载 npm 版npm uninstall -g wasp.sh/wasp-cli确认 Wasp 已从系统卸载type wasp卸载干净时type输出 not found否则会打印wasp二进制的路径此时需手动删除该文件。这一步同时可作为迁移成功的验证手段迁移并安装 npm 版后type wasp应指向 npm 全局 bin 目录下的包装入口。删除 npm 标记文件即前文源码中NPM_MARKER_FILE对应的文件rm $HOME/.local/share/wasp-lang/.uses-npm重新运行旧安装器并指定所需版本curl -sSL https://get.wasp.sh/installer.sh | sh -s -- -v x.y.z3. Apple SiliconM 系列芯片Mac 上出现 Bad CPU type in executable这是脚本安装器分发的 x86 二进制在 Apple Silicon 上无法直接运行的典型报错文档给出两个选项**推荐**迁移到 npm 安装方式npm 版原生支持 Apple Silicon继续使用旧安装器但先为 Mac 安装 Rosetta 以运行 x86 二进制softwareupdate --install-rosetta安装完成后 Wasp 即可按正常方式运行。小结Wasp 安装方式的迁移本质上是一次「分发渠道 版本策略」的收敛脚本安装器冻结在 0.20.x 且不再受支持0.20.2 起的版本统一经由 npm 全局包wasp.sh/wasp-cli分发最低要求 Node.js 24.14.1。迁移动作本身只是一条migrate-to-npm命令但围绕它的冲突检测.uses-npm标记、平台子包分发platform/arch/libc 三元组与 Node 版本校验共同保证了新旧两种安装方式不会在同一台机器上互相踩踏。完成迁移后type wasp指向 npm 全局 bin、wasp可正常执行即代表工作站已成功切换CI 环境同理替换安装步骤即可。【免费下载链接】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），仅供参考