open-saas 安装卡住，常见原因不是代码，而是 Node.js、Docker 或 Wasp CLI 版本没有对齐。先把环境检查做完，再创建项目，排错会轻松很多。例如页面出现注册按钮却无法提交，就要回到服务端终端和数据库状态找原因。以下步骤面向本地开发环境，Windows 应在 WSL2 中执行。

安装前先过三项检查

官方入门页写的是 Node.js 22.12 以上，但截至 2026 年 7 月 16 日，npm 上的 Wasp CLI 0.24.0 声明需要 Node.js 24.14.1 以上。为避免引擎报错，建议直接使用 Node.js 24.14.1 或更新版本，并确认 Git、Docker 已启动。

node -v
git --version
docker --version
npm i -g @wasp.sh/wasp-cli
wasp version

用稳定模板创建项目

wasp new my-saas -t saas
cd my-saas/app
wasp start db

命令会把项目写入当前目录下的 my-saas，其中 app 是主应用，blog 是内容站点，e2e-tests 放端到端测试。数据库进程要保持运行。另开终端进入同一 app 目录，执行迁移、复制环境变量样例，再启动开发服务。

wasp db migrate-dev
cp .env.server.example .env.server
wasp start

怎样算安装成功

1. 浏览器能打开 http://localhost:3000。
2. 注册账号后，服务端终端能看到模拟邮件验证链接。
3. 修改 schema.prisma 后，迁移命令能正常完成。

开发时通常会同时占用前端 3000、服务端 3001 和数据库 5432 端口。若页面打不开，先确认三个进程是否都在运行，再检查端口是否被其他程序占用。支付、Google 登录、真实邮件、OpenAI 与 S3 都不是首次启动的硬条件；准备启用相应功能时，再把密钥写入 .env.server 或 .env.client，别把密钥提交到仓库。

源码克隆适合什么情况

需要研究模板实现或参与贡献时，可执行 git clone https://github.com/wasp-lang/open-saas.git。当前 main 分支的模板声明 Wasp 0.25，而稳定 CLI 仍为 0.24.0，新项目优先使用 wasp new，不要把主分支版本差异误判成安装失败。Apple 芯片若遇到兼容问题，再按官方提示检查 Rosetta。

交付前的快速清单

• Wasp 版本命令能返回结果，Docker 容器正常启动。
• 注册、验证链接、登录和数据库迁移均已实际测试。
• 环境变量文件已排除在 Git 提交之外。

若迁移提示数据库连接失败，先重启 wasp start db，不要急着删除项目；若 CLI 报 Node 引擎不满足，则切换到符合要求的 Node 版本后重新安装 CLI。