Wasp 快速上手指南：3 步创建并运行你的第一个全栈 JS/TS 应用-平芜编程栈

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

【免费下载链接】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 官方 Quick Start 为核心，带你从零完成 Wasp CLI 的安装、新项目的创建与本地启动，全程只需 3 条命令。读完后你将掌握wasp new、wasp start、wasp clean等核心命令的用法，了解 Wasp 对 Node.js 环境的要求，以及如何在 Linux、macOS（Apple Silicon）、Windows WSL2 上规避常见坑位，并快速进入官方 Todo 教程继续深入 Wasp 的核心能力。

前置要求：Node.js 与 npm

Wasp 是构建在 Node.js 生态之上的全栈框架，因此在安装 Wasp 之前，你需要确保机器上已安装Node.js（以及随附的 npm），并且它们位于终端PATH环境变量中。

关联文档（Wasp 0.17）要求 Node.js>= 20；
从当前仓库源码 Wasp/Node/Version.hs 可以看到，较新版本的 Wasp 已将最低支持版本提升到Node 24.14.1、npm 11.11.0（源码注释明确说明「通常与最新 LTS 保持一致」），因此实际安装时建议直接使用最新 LTS 版本的 Node.js。

Wasp 在运行时会主动校验 Node/npm 版本是否满足要求，而不是等到报错才提示。ValidNodeAndNpm这一前置检查（见 Require/ValidNodeAndNpm.hs）会在任何需要执行 Node.js 的命令（编译、运行生成的应用、npm install、Prisma、部署等）之前运行，若版本不达标会直接给出明确错误，例如：

Your node version does not meet Wasp's requirements! You are running node 18.12.0. Wasp requires node version 24.14.1 or higher.

如果不想手动管理 Node.js 版本，官方推荐使用nvm（Node Version Manager）来安装与切换版本：

# 通过系统包管理器或 nvm 官方安装脚本安装 nvm 后： nvm install 20 # 安装你需要的版本（此处以 20 为例） nvm use 20 # 为当前 shell 会话切换版本 node -v # 校验当前生效的 Node.js 版本

三步快速创建并运行第一个 Wasp 应用

第 1 步：安装 Wasp

在Linux / macOS / WSL（Windows）的终端中执行官方安装脚本：

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

安装完成后，可以在终端中运行wasp --version或wasp doctor（后者会额外检查 Node/npm、数据库等环境依赖）确认 CLI 已就绪。

第 2 步：创建新应用

wasp new

wasp new是一个交互式命令：它会引导你输入项目名称，并从模板列表中选择起始模板。从当前仓库源码 AvailableTemplates.hs 可以看到，Wasp CLI 目前内置了以下可选模板：

模板	说明	类型
`basic`（默认）	包含最常见用例示例的基础模板，开箱即用，如认证、任务列表、标签等	随 CLI 打包（Bundled）
`minimal`	只有一个页面的极简模板	随 CLI 打包（Bundled）
`saas`	一个 SaaS 所需的全部能力：Auth、ChatGPT API、Tailwind、Stripe 支付等	从 GitHub Release 归档拉取（GhRepoReleaseArchive）

其中basic是默认选项，其main.wasp.ts（见 starters/basic/main.wasp.ts）已经预置了完整的邮件认证（登录、注册、密码重置、邮箱验证页面）、任务（Task）与标签（Tag）两个功能模块的示例代码，以及对应的 Prisma 数据模型（见 starters/basic/schema.prisma），非常适合快速体验 Wasp 的「声明式全栈」开发方式。

而minimal模板（见 starters/minimal/main.wasp.ts）则极为精简——整个应用只有app定义 + 一个根路由"/"指向MainPage，适合想从最干净的项目结构开始学习的读者。

第 3 步：运行应用

cd <my-project-name> wasp start

就这么简单 🎉 —— Wasp 会同时为你启动前端（React）和后端（Node.js），浏览器访问 http://localhost:3000 即可看到你的应用。

值得注意的是，从源码 Start.hs 可以看出，wasp start并不是简单地启动一个开发服务器，它实际做了这几件事：

编译 Wasp 声明式代码：读取main.wasp.ts、schema.prisma及src/目录，生成完整的全栈应用代码（存放在项目的.wasp/out目录）；
检查并建立数据库连接：需要本地 PostgreSQL（或 SQLite，取决于项目配置）可用，否则会在此步报错；
监听文件变化：使用watch并行监听项目源码与生成代码，任何改动都会触发重新编译并热重启前后端——这就是「Wasp 同时服务前后端」的核心实现；
按需展示编译警告/错误：即使生成应用在后台输出大量日志，Wasp 也会在合适的时机把最新一次的编译警告与错误再次打印出来，确保你不会错过任何编译问题。

此外，wasp start还支持通过命令行参数自定义端口（如--client-port/--server-port），相关解析逻辑见 Start/ArgumentsParser.hs。

首次运行前的数据库准备

对于带有数据模型的项目（例如默认的basic模板包含 User、Task、Tag 等实体），首次运行前需要初始化数据库。在项目目录下执行：

wasp db migrate-dev

该命令会把schema.prisma中的实体同步为数据库表结构并生成迁移文件。如果尚未启动本地数据库服务，也可以先用：

wasp db start

启动开发用数据库（内部基于 Docker 运行 PostgreSQL，见 wasp-app-runner/src/db/postgres.ts）。

平台专项说明

macOS（Apple Silicon / M 系列芯片）

Wasp 的 CLI 二进制目前主要面向 x86 架构构建。如果你在 M1/M2 等 arm64 设备上遇到Bad CPU type in executable错误，需要安装Rosetta（Apple 提供的 x86 翻译层）：

softwareupdate --install-rosetta

安装完成后即可正常运行 Wasp。

Windows（WSL2）

Wasp 在原生 Windows 上仍存在少量兼容性问题，官方推荐的最佳实践是使用WSL2（Windows Subsystem for Linux）：

在 WSL 中安装 Ubuntu（参考微软官方 WSL 安装文档）；
在 WSL 的 Ubuntu 终端里按照 Linux 方式安装 Wasp；
重要提醒：WSL2 下务必把 Wasp 项目放在Linux 文件系统（如~/目录）中，而不是 Windows 文件系统（如/mnt/c/...），否则由于 WSL2 的文件监听机制限制，Wasp 将无法检测到文件变更，热更新会失效。

从源码构建安装

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

克隆 wasp 仓库（本仓库即GitHub_Trending/wa/wasp）；
安装 Cabal（Haskell 构建工具）；
在waspc/目录下执行cabal install。

Wasp 的 CLI 主体是 Haskell 编写的（入口见 waspc/cli/exe/Main.hs，核心逻辑位于 waspc/cli/src/Wasp），首次构建会因下载依赖耗时较长，请耐心等待。项目级构建配置可参考 waspc/waspc.cabal。

卡住了？试试`wasp clean`

如果你在开发过程中遇到奇怪的报错（例如依赖状态错乱、生成代码残留），wasp clean就是 Wasp 版的「重启大法」。从源码 Clean.hs 可以看到，它做了两件事：

删除项目的node_modules目录；
删除项目的.wasp目录（该目录存放生成的代码与项目锁）。

清理完成后，再运行wasp install重新安装依赖即可恢复干净状态（wasp install会重新执行 npm 安装，见 Install.hs）。如果问题依旧，建议带上错误日志到 Wasp 的 GitHub 仓库或 Discord 社区反馈。

接下来学什么？

👉完成 Todo App 官方教程：它会带你走一遍 Wasp 的全部核心功能（页面、实体、查询、操作、认证等），这是官方强烈推荐的下一步；
配置你的编辑器：参考 editor-setup.md，为 Wasp 的 TypeScript 规范文件（main.wasp.ts）获得语法高亮与智能提示；
了解项目结构：阅读 02-project-structure.md，理解main.wasp.ts、src/与生成代码.wasp/out之间的关系。

附：快速参考卡片

命令	作用
`curl -sSL https://get.wasp.sh/installer.sh \\| sh`	安装 Wasp CLI（Linux / macOS / WSL）
`wasp new`	交互式创建新项目（可选 basic / minimal / saas 模板）
`wasp start`	编译并同时启动前端（:3000）与后端（:3001），支持热更新
`wasp db migrate-dev`	将 Prisma 实体同步到数据库并生成迁移
`wasp db start`	启动开发用数据库（Docker 运行 PostgreSQL）
`wasp clean`	清理`node_modules`与`.wasp`生成目录
`wasp install`	重新安装项目依赖
`wasp doctor`	检查 Node/npm 等环境依赖是否满足要求

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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