Wasp 快速上手指南：三步创建并运行你的第一个全栈应用

Wasp 快速上手指南：三步创建并运行你的第一个全栈应用

【免费下载链接】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（waspc 仓库对应的 0.16 版本文档）的官方 Quick Start 深度解析，面向想要在几分钟内跑通"从零到启动一个全栈 Web 应用"流程的开发者。读完本文，你将掌握 Wasp 的安装方式（含 Linux/macOS/Windows WSL/源码编译四种途径）、wasp new与wasp start两个核心命令的完整用法与背后实现原理，并知道接下来如何通过 Todo App 教程 深入学习框架的核心功能。

三步快速开始

Wasp 的设计目标是用最少的步骤带你完成"创建并运行第一个全栈应用"。整个过程只需三条命令：

1. 安装 Wasp（Linux / macOS / WSL）：

   curl -sSL https://get.wasp.sh/installer.sh | sh

   安装脚本会在完成后提示你接下来如何操作。Wasp 的运行依赖 Node.js，如果机器上缺少 Node.js，安装或后续命令会给出明确警告，详细要求见下文 环境要求。

2. 创建新应用：

   wasp new

   该命令会以交互方式让你输入项目名称并选择 Starter 模板，然后在当前目录下生成一个完整可运行的项目骨架。

3. 启动应用：

   cd <my-project-name> wasp start

执行完第三步后，Wasp 会同时为你启动前端和后端，访问 http://localhost:3000 即可看到你的第一个全栈 Web 应用。

💡 想更快？可以试试 Wasp AI（Mage）创建新应用：只需提供应用标题和一段简短描述，就能在几分钟内生成一个新的 Wasp 应用。

环境要求

在安装 Wasp 之前，请确认你的机器满足以下条件：

• 已安装Node.js 和 npm，并且二者位于PATH环境变量中；
• Node.js 版本>= 20（本 0.16 版本文档的要求）。

注意：不同版本对 Node.js 的最低要求会随版本演进而变化。例如当前仓库源码（waspc）中定义的版本下限已经更新为 Node.js 24.14.1、npm 11.11.0（见 waspc/src/Wasp/Node/Version.hs）。因此在使用较新版本的 Wasp 时，请以wasp new、wasp start实际输出的提示为准——这正是下文"版本校验机制"要讲的内容。

使用 nvm 管理 Node.js 版本

官方推荐使用 nvm 来管理 Node.js 的安装与切换：

# 安装一个你需要的 Node.js 版本 nvm install 20 # 为当前 shell 会话切换到指定版本 nvm use 20 # 查看当前 shell 会话实际使用的 Node.js 版本 node -v

nvm 本身可以通过系统的包管理器（如apt、pacman、homebrew）安装，也可以直接运行其官方安装脚本。对于多项目并行开发的场景，nvm 能确保每个项目都使用其所需的 Node.js 版本，避免版本冲突。

安装详解（分平台说明）

Linux / macOS

在终端中运行官方安装脚本即可：

curl -sSL https://get.wasp.sh/installer.sh | sh

Apple Silicon（M1/M2 等 arm64 芯片）特殊说明

如果你在 arm64 架构的 Mac 上遇到"Bad CPU type in executable"错误，原因在于 Wasp 二进制当前按 x86 架构构建、尚未提供 arm64 版本。解决办法是为你的 Mac 安装Rosetta（苹果提供的 x86 翻译层，让 arm64 芯片可以运行 x86 应用）：

softwareupdate --install-rosetta

安装完成 Rosetta 后，Wasp 即可正常运行。这是从文档明确记录的已知平台限制，如果你需要确认最新版本的架构支持情况，建议查看对应版本的 ChangeLog 或 release 说明。

Windows

Wasp 在 Windows 上的原生支持仍在完善中：虽然已经可以在 Windows 上完成编译和运行，但仍存在个别阻碍完全可用的 bug。当前在 Windows 上最推荐的方式是使用WSL（Windows Subsystem for Linux）：

1. 在 Windows 上安装 WSL（官方提供wsl --install一键安装方式）；
2. 在 WSL 中安装 Ubuntu 等发行版；
3. 在 WSL 的 Linux 环境内按照上文"Linux / macOS"的步骤安装 Wasp。

⚠️WSL2 使用警告：请务必把 Wasp 项目放在Linux 文件系统下，而不是 Windows 文件系统（如/mnt/c/...）。由于 WSL2 的文件系统桥接问题，放在 Windows 文件系统上的项目将无法被 Wasp 正确检测到文件变更（wasp start的热重载功能会失效）。

从源码构建

如果官方安装脚本在你的操作系统上不可用或不受支持，也可以直接从源码构建 Wasp：

1. 克隆本仓库（GitHub_Trending/wa/wasp，即waspc所在的仓库）；
2. 安装 Cabal；
3. 进入waspc/目录执行cabal install。

首次构建时 Cabal 需要下载大量依赖，耗时较长属正常现象。Wasp 的 CLI 主体是 Haskell 实现（入口见 waspc/cli/exe/Main.hs，核心命令模块位于 waspc/cli/src/Wasp/Cli），而应用的生成器与各类包则大量使用 TypeScript（见 waspc/data/Generator 与 waspc/data/packages）。

wasp new背后发生了什么

wasp new不是简单地复制一个空目录，从源码 waspc/cli/src/Wasp/Cli/Command/CreateNewProject.hs 可以看到它依次做了四件事：

1. 校验环境：通过require检查 Node.js / npm 版本是否满足要求（对应ValidNodeAndNpm这一 Requirable 类型，见 waspc/cli/src/Wasp/Cli/Command/Require/ValidNodeAndNpm.hs）。如果版本不达标，会在早期阶段就给出清晰错误，而不是等到编译时才失败；
2. 解析参数并确定模板：交互式收集项目名，并从可用的 Starter 模板中选择一个（内置模板清单见 waspc/data/Cli/starters）；
3. 从模板生成项目：把选定模板的文件复制到目标目录；
4. 自动安装依赖：在新项目目录内执行依赖安装（等价于wasp install）。如果这一步失败，CLI 会打印黄色警告并提示你稍后在项目目录中手动运行wasp install——项目本身已经创建成功，不影响继续使用；
5. 打印启动指引：输出"Created a new Wasp app in./<project-name>"以及下一步操作提示。

内置 Starter 模板

仓库的 waspc/data/Cli/starters 目录内置了三种模板，供wasp new交互选择（也可以通过-t参数直接指定，例如wasp new my-app -t basic）：

• minimal：最小可运行骨架，只有一个首页路由。其 main.wasp.ts 只有十几行，集中展示了 Wasp 声明式配置的核心结构：app(...)定义应用名与标题，spec数组用route(...)与page(...)声明"URL 路径 → React 页面"的映射；
• basic：一个功能更完整的 ToDo 应用模板（其自述文档见 waspc/data/Cli/starters/basic/README.md）。它演示了 Wasp 的大多数核心能力：邮箱登录/注册/邮箱验证/密码重置（main.wasp.ts 中的auth与emailSender配置）、Queries/Actions（见src/tasks/与src/tags/下的queries.ts、actions.ts）以及任务、标签两类实体；
• skeleton：最基础的工程骨架，包含tsconfig、vite.config、.gitignore等配置文件，适合希望完全从零手写代码的开发者。

无论选择哪种模板，生成的项目都是一个标准的 Wasp 工程：根目录有声明式配置文件main.wasp.ts、数据模型文件schema.prisma、前端源码src/目录以及package.json，同时main.wasp.ts中的__waspAppName__、__waspVersion__等占位符会在生成时被替换为实际的项目名与当前 Wasp 版本。

wasp start背后发生了什么

wasp start是开发期的核心命令。从 waspc/cli/src/Wasp/Cli/Command/Start.hs 可以看到它的工作流：

1. 周期性检查并展示官方 News（避免在 CI 等场景下频繁打扰）；
2. 确认处于 Wasp 项目内（要求InWaspProject），并确定生成目录outDir；
3. 编译 Wasp 代码（compile）：解析main.wasp.ts声明、Prisma schema 与src/中的引用代码，生成完整的 React + Node.js + Prisma 全栈工程，期间产生的 warnings/errors 会打印出来；
4. 计算前端与后端的运行配置与 URL（开发服务器默认端口等信息）；
5. 进入 watch 模式（waspc/cli/src/Wasp/Cli/Command/Watch.hs）：监听文件变更，自动重新编译并重启生成的工程。

也就是说，wasp start一次命令同时管理了前端 dev server、后端 server 与数据库连接，你不需要手动启动多个进程。这也是 Wasp"batteries-included"体验的体现：框架把所有全栈样板（RPC、类型安全、认证基础设施等）抽象在生成层，你只需关注业务代码。

补充：如果你的应用使用了数据库实体，wasp start需要数据库连接可用（CLI 会校验DbConnectionEstablished）。在开发期可以使用wasp start db启动一个托管的开发数据库（实现见 waspc/cli/src/Wasp/Cli/Command/Start/Db.hs），或运行wasp db migrate-dev把 Prisma 迁移应用到数据库——这些命令的详细说明见 数据库文档 的对应版本。

Node/npm 版本校验机制

无论是wasp new还是编译/运行阶段，CLI 都会调用 waspc/src/Wasp/Node/Version.hs 中的checkUserNodeAndNpmMeetWaspRequirements做双重检查：

• 通过node --version、npm --version读取当前版本并解析为语义化版本；
• 与 Wasp 支持的最低版本比较，不达标时报错："Your node version does not meet Wasp's requirements!" 并给出当前版本与要求版本；
• 命令不存在（未安装）或退出码非零时，会提示"nodecommand not found!"或给出具体 exit code。

这意味着即使文档没有覆盖你的 Node.js 版本组合，CLI 也会在你运行任何命令时第一时间给出准确的版本提示，无需手动排障。

安装或运行遇到问题？

如果你在执行上述步骤时遇到任何问题，可以按以下思路排查：

如果上述方案仍无法解决，建议带着完整的终端输出去 Wasp 社区（Discord）提问，附上你的操作系统、Node.js 版本与 Wasp 版本，能显著提高问题定位效率。

接下来学什么

• 👉 强烈推荐继续 Todo App 教程：从创建项目开始，一步步带你体验 Wasp 的核心特性（页面、实体、Queries/Actions、认证等）；
• 配置你的编辑器：为 VS Code 等编辑器安装 Wasp 扩展，获得 Wasp 文件的语法高亮、代码补全与诊断；
• 用 Wasp AI 创建新应用：通过 Mage（usemage.ai）或本地的wasp new+ AI 生成，快速得到带业务逻辑的起步应用；
• 想了解框架如何被构建与测试：可以阅读仓库中的 waspc/README.md 与 waspc/ChangeLog.md，前者说明了waspc（Wasp 编译器/CLI）的架构，后者记录了各版本的功能演进。

【免费下载链接】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