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本文是 Waspwaspc 仓库对应的 0.16 版本文档的官方 Quick Start 深度解析面向想要在几分钟内跑通从零到启动一个全栈 Web 应用流程的开发者。读完本文你将掌握 Wasp 的安装方式含 Linux/macOS/Windows WSL/源码编译四种途径、wasp new与wasp start两个核心命令的完整用法与背后实现原理并知道接下来如何通过 Todo App 教程 深入学习框架的核心功能。三步快速开始Wasp 的设计目标是用最少的步骤带你完成创建并运行第一个全栈应用。整个过程只需三条命令安装 WaspLinux / macOS / WSLcurl -sSL https://get.wasp.sh/installer.sh | sh安装脚本会在完成后提示你接下来如何操作。Wasp 的运行依赖 Node.js如果机器上缺少 Node.js安装或后续命令会给出明确警告详细要求见下文 环境要求。创建新应用wasp new该命令会以交互方式让你输入项目名称并选择 Starter 模板然后在当前目录下生成一个完整可运行的项目骨架。启动应用cd my-project-name wasp start执行完第三步后Wasp 会同时为你启动前端和后端访问 http://localhost:3000 即可看到你的第一个全栈 Web 应用。 想更快可以试试 Wasp AIMage创建新应用只需提供应用标题和一段简短描述就能在几分钟内生成一个新的 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 -vnvm 本身可以通过系统的包管理器如apt、pacman、homebrew安装也可以直接运行其官方安装脚本。对于多项目并行开发的场景nvm 能确保每个项目都使用其所需的 Node.js 版本避免版本冲突。安装详解分平台说明Linux / macOS在终端中运行官方安装脚本即可curl -sSL https://get.wasp.sh/installer.sh | shApple SiliconM1/M2 等 arm64 芯片特殊说明如果你在 arm64 架构的 Mac 上遇到Bad CPU type in executable错误原因在于 Wasp 二进制当前按 x86 架构构建、尚未提供 arm64 版本。解决办法是为你的 Mac 安装Rosetta苹果提供的 x86 翻译层让 arm64 芯片可以运行 x86 应用softwareupdate --install-rosetta安装完成 Rosetta 后Wasp 即可正常运行。这是从文档明确记录的已知平台限制如果你需要确认最新版本的架构支持情况建议查看对应版本的 ChangeLog 或 release 说明。WindowsWasp 在 Windows 上的原生支持仍在完善中虽然已经可以在 Windows 上完成编译和运行但仍存在个别阻碍完全可用的 bug。当前在 Windows 上最推荐的方式是使用WSLWindows Subsystem for Linux在 Windows 上安装 WSL官方提供wsl --install一键安装方式在 WSL 中安装 Ubuntu 等发行版在 WSL 的 Linux 环境内按照上文Linux / macOS的步骤安装 Wasp。⚠️WSL2 使用警告请务必把 Wasp 项目放在Linux 文件系统下而不是 Windows 文件系统如/mnt/c/...。由于 WSL2 的文件系统桥接问题放在 Windows 文件系统上的项目将无法被 Wasp 正确检测到文件变更wasp start的热重载功能会失效。从源码构建如果官方安装脚本在你的操作系统上不可用或不受支持也可以直接从源码构建 Wasp克隆本仓库GitHub_Trending/wa/wasp即waspc所在的仓库安装 Cabal进入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 可以看到它依次做了四件事校验环境通过require检查 Node.js / npm 版本是否满足要求对应ValidNodeAndNpm这一 Requirable 类型见 waspc/cli/src/Wasp/Cli/Command/Require/ValidNodeAndNpm.hs。如果版本不达标会在早期阶段就给出清晰错误而不是等到编译时才失败解析参数并确定模板交互式收集项目名并从可用的 Starter 模板中选择一个内置模板清单见 waspc/data/Cli/starters从模板生成项目把选定模板的文件复制到目标目录自动安装依赖在新项目目录内执行依赖安装等价于wasp install。如果这一步失败CLI 会打印黄色警告并提示你稍后在项目目录中手动运行wasp install——项目本身已经创建成功不影响继续使用打印启动指引输出Created a new Wasp app in./project-name以及下一步操作提示。内置 Starter 模板仓库的 waspc/data/Cli/starters 目录内置了三种模板供wasp new交互选择也可以通过-t参数直接指定例如wasp new my-app -t basicminimal最小可运行骨架只有一个首页路由。其 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 可以看到它的工作流周期性检查并展示官方 News避免在 CI 等场景下频繁打扰确认处于 Wasp 项目内要求InWaspProject并确定生成目录outDir编译 Wasp 代码compile解析main.wasp.ts声明、Prisma schema 与src/中的引用代码生成完整的 React Node.js Prisma 全栈工程期间产生的 warnings/errors 会打印出来计算前端与后端的运行配置与 URL开发服务器默认端口等信息进入 watch 模式waspc/cli/src/Wasp/Cli/Command/Watch.hs监听文件变更自动重新编译并重启生成的工程。也就是说wasp start一次命令同时管理了前端 dev server、后端 server 与数据库连接你不需要手动启动多个进程。这也是 Waspbatteries-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 Wasps requirements! 并给出当前版本与要求版本命令不存在未安装或退出码非零时会提示nodecommand not found!或给出具体 exit code。这意味着即使文档没有覆盖你的 Node.js 版本组合CLI 也会在你运行任何命令时第一时间给出准确的版本提示无需手动排障。安装或运行遇到问题如果你在执行上述步骤时遇到任何问题可以按以下思路排查现象可能原因处理方式提示nodecommand not found未安装 Node.js 或不在 PATH安装 Node.js 20或用nvm install 20 nvm use 20提示 node 版本不满足要求Node.js 版本过低升级 Node.js或使用nvm use 更高版本Apple Silicon 报 Bad CPU type in executable缺少 Rosetta 翻译层运行softwareupdate --install-rosettaWSL2 下文件变更不生效项目位于 Windows 文件系统把项目移动到 Linux 文件系统~/下wasp start提示依赖安装失败网络或 npm 源问题在项目目录运行wasp install重试数据库相关报错未准备开发数据库运行wasp start db或wasp db migrate-dev如果上述方案仍无法解决建议带着完整的终端输出去 Wasp 社区Discord提问附上你的操作系统、Node.js 版本与 Wasp 版本能显著提高问题定位效率。接下来学什么 强烈推荐继续 Todo App 教程从创建项目开始一步步带你体验 Wasp 的核心特性页面、实体、Queries/Actions、认证等配置你的编辑器为 VS Code 等编辑器安装 Wasp 扩展获得 Wasp 文件的语法高亮、代码补全与诊断用 Wasp AI 创建新应用通过 Mageusemage.ai或本地的wasp new AI 生成快速得到带业务逻辑的起步应用想了解框架如何被构建与测试可以阅读仓库中的 waspc/README.md 与 waspc/ChangeLog.md前者说明了waspcWasp 编译器/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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本文是 Waspwaspc 仓库对应的 0.16 版本文档的官方 Quick Start 深度解析面向想要在几分钟内跑通从零到启动一个全栈 Web 应用流程的开发者。读完本文你将掌握 Wasp 的安装方式含 Linux/macOS/Windows WSL/源码编译四种途径、wasp new与wasp start两个核心命令的完整用法与背后实现原理并知道接下来如何通过 Todo App 教程 深入学习框架的核心功能。三步快速开始Wasp 的设计目标是用最少的步骤带你完成创建并运行第一个全栈应用。整个过程只需三条命令安装 WaspLinux / macOS / WSLcurl -sSL https://get.wasp.sh/installer.sh | sh安装脚本会在完成后提示你接下来如何操作。Wasp 的运行依赖 Node.js如果机器上缺少 Node.js安装或后续命令会给出明确警告详细要求见下文 环境要求。创建新应用wasp new该命令会以交互方式让你输入项目名称并选择 Starter 模板然后在当前目录下生成一个完整可运行的项目骨架。启动应用cd my-project-name wasp start执行完第三步后Wasp 会同时为你启动前端和后端访问 http://localhost:3000 即可看到你的第一个全栈 Web 应用。 想更快可以试试 Wasp AIMage创建新应用只需提供应用标题和一段简短描述就能在几分钟内生成一个新的 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 -vnvm 本身可以通过系统的包管理器如apt、pacman、homebrew安装也可以直接运行其官方安装脚本。对于多项目并行开发的场景nvm 能确保每个项目都使用其所需的 Node.js 版本避免版本冲突。安装详解分平台说明Linux / macOS在终端中运行官方安装脚本即可curl -sSL https://get.wasp.sh/installer.sh | shApple SiliconM1/M2 等 arm64 芯片特殊说明如果你在 arm64 架构的 Mac 上遇到Bad CPU type in executable错误原因在于 Wasp 二进制当前按 x86 架构构建、尚未提供 arm64 版本。解决办法是为你的 Mac 安装Rosetta苹果提供的 x86 翻译层让 arm64 芯片可以运行 x86 应用softwareupdate --install-rosetta安装完成 Rosetta 后Wasp 即可正常运行。这是从文档明确记录的已知平台限制如果你需要确认最新版本的架构支持情况建议查看对应版本的 ChangeLog 或 release 说明。WindowsWasp 在 Windows 上的原生支持仍在完善中虽然已经可以在 Windows 上完成编译和运行但仍存在个别阻碍完全可用的 bug。当前在 Windows 上最推荐的方式是使用WSLWindows Subsystem for Linux在 Windows 上安装 WSL官方提供wsl --install一键安装方式在 WSL 中安装 Ubuntu 等发行版在 WSL 的 Linux 环境内按照上文Linux / macOS的步骤安装 Wasp。⚠️WSL2 使用警告请务必把 Wasp 项目放在Linux 文件系统下而不是 Windows 文件系统如/mnt/c/...。由于 WSL2 的文件系统桥接问题放在 Windows 文件系统上的项目将无法被 Wasp 正确检测到文件变更wasp start的热重载功能会失效。从源码构建如果官方安装脚本在你的操作系统上不可用或不受支持也可以直接从源码构建 Wasp克隆本仓库GitHub_Trending/wa/wasp即waspc所在的仓库安装 Cabal进入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 可以看到它依次做了四件事校验环境通过require检查 Node.js / npm 版本是否满足要求对应ValidNodeAndNpm这一 Requirable 类型见 waspc/cli/src/Wasp/Cli/Command/Require/ValidNodeAndNpm.hs。如果版本不达标会在早期阶段就给出清晰错误而不是等到编译时才失败解析参数并确定模板交互式收集项目名并从可用的 Starter 模板中选择一个内置模板清单见 waspc/data/Cli/starters从模板生成项目把选定模板的文件复制到目标目录自动安装依赖在新项目目录内执行依赖安装等价于wasp install。如果这一步失败CLI 会打印黄色警告并提示你稍后在项目目录中手动运行wasp install——项目本身已经创建成功不影响继续使用打印启动指引输出Created a new Wasp app in./project-name以及下一步操作提示。内置 Starter 模板仓库的 waspc/data/Cli/starters 目录内置了三种模板供wasp new交互选择也可以通过-t参数直接指定例如wasp new my-app -t basicminimal最小可运行骨架只有一个首页路由。其 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 可以看到它的工作流周期性检查并展示官方 News避免在 CI 等场景下频繁打扰确认处于 Wasp 项目内要求InWaspProject并确定生成目录outDir编译 Wasp 代码compile解析main.wasp.ts声明、Prisma schema 与src/中的引用代码生成完整的 React Node.js Prisma 全栈工程期间产生的 warnings/errors 会打印出来计算前端与后端的运行配置与 URL开发服务器默认端口等信息进入 watch 模式waspc/cli/src/Wasp/Cli/Command/Watch.hs监听文件变更自动重新编译并重启生成的工程。也就是说wasp start一次命令同时管理了前端 dev server、后端 server 与数据库连接你不需要手动启动多个进程。这也是 Waspbatteries-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 Wasps requirements! 并给出当前版本与要求版本命令不存在未安装或退出码非零时会提示nodecommand not found!或给出具体 exit code。这意味着即使文档没有覆盖你的 Node.js 版本组合CLI 也会在你运行任何命令时第一时间给出准确的版本提示无需手动排障。安装或运行遇到问题如果你在执行上述步骤时遇到任何问题可以按以下思路排查现象可能原因处理方式提示nodecommand not found未安装 Node.js 或不在 PATH安装 Node.js 20或用nvm install 20 nvm use 20提示 node 版本不满足要求Node.js 版本过低升级 Node.js或使用nvm use 更高版本Apple Silicon 报 Bad CPU type in executable缺少 Rosetta 翻译层运行softwareupdate --install-rosettaWSL2 下文件变更不生效项目位于 Windows 文件系统把项目移动到 Linux 文件系统~/下wasp start提示依赖安装失败网络或 npm 源问题在项目目录运行wasp install重试数据库相关报错未准备开发数据库运行wasp start db或wasp db migrate-dev如果上述方案仍无法解决建议带着完整的终端输出去 Wasp 社区Discord提问附上你的操作系统、Node.js 版本与 Wasp 版本能显著提高问题定位效率。接下来学什么 强烈推荐继续 Todo App 教程从创建项目开始一步步带你体验 Wasp 的核心特性页面、实体、Queries/Actions、认证等配置你的编辑器为 VS Code 等编辑器安装 Wasp 扩展获得 Wasp 文件的语法高亮、代码补全与诊断用 Wasp AI 创建新应用通过 Mageusemage.ai或本地的wasp new AI 生成快速得到带业务逻辑的起步应用想了解框架如何被构建与测试可以阅读仓库中的 waspc/README.md 与 waspc/ChangeLog.md前者说明了waspcWasp 编译器/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考