Wasp Starter Templates 实战指南：用 `wasp new` 一键搭建全栈应用脚手架

Wasp Starter Templates 实战指南：用wasp new一键搭建全栈应用脚手架

【免费下载链接】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 官方为开发者内置了一组 Starter Templates（起步模板），覆盖从「最简单的单页应用」到「开箱即用的 SaaS」再到「AI 生成式脚手架」的多种起点。本文以 Wasp 0.14 版本的模板文档为主线，完整讲解wasp new的交互式创建流程、全部可用模板的适用场景与特性，并结合本仓库waspc的 Haskell 源码揭示模板的底层实现机制（骨架复制、占位符替换、远程模板拉取），读完你不仅能熟练挑选模板快速起项目，还能理解模板系统的工作原理。

为什么需要 Starter Templates

当你有一个新的产品想法时，最不想把时间浪费在搭建通用基础设施上——认证（Auth）、数据库、邮件、支付这些每个应用都要面对的东西。这正是 Starter Templates 存在的意义：把常见能力预先封装成可直接运行的工程骨架，wasp new一条命令即可基于模板生成完整项目，随后直接在源码上做业务开发。

模板不止是「样板代码」，它本身就是 Wasp 声明式能力的活教材：通过阅读模板中的main.wasp.ts、schema.prisma与src/目录结构，你可以快速掌握 Wasp 项目中页面、实体、Query/Action、Auth 的写法。

使用模板：wasp new交互式创建流程

运行wasp new即可进入交互模式创建新项目，CLI 会依次询问项目名与模板选择：

$ wasp new Enter the project name (e.g. my-project) ▸ MyFirstProject Choose a starter template [1] basic (default) Simple starter template with a single page. [2] todo-ts Simple but well-rounded Wasp app implemented with Typescript & full-stack type safety. [3] saas Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details. [4] embeddings Comes with code for generating vector embeddings and performing vector similarity search. [5] ai-generated 🤖 Describe an app in a couple of sentences and have Wasp AI generate initial code for you. (experimental) ▸ 1 🐝 --- Creating your project from the "basic" template... ------------------------- Created new Wasp app in ./MyFirstProject directory! To run your new app, do: cd MyFirstProject wasp db start

从上面对话可以看出，交互模式下你可以用方向键选择模板（回车确认），不选则默认使用basic。创建完成后，进入项目目录并执行wasp db start启动开发数据库，随后wasp start即可启动应用。

如果你不想走交互流程，也可以直接通过命令行参数一步到位。从 ArgumentsParser.hs 可以看到wasp new支持两个可选参数：位置参数PROJECT_NAME（项目名）与-t/--template（模板名）。当你在命令行中显式提供了项目名但没有提供-t时，CLI 会直接采用默认模板而不进入交互选择（见 ProjectDescription.hs）。

项目命名规则

在 ProjectDescription.hs 中，项目名在创建前会经过校验，同时会被自动转换为 Wasp 应用的 App 名（kebab-case 转 camelCase）：

• 必须以字母或下划线开头；
• 只能包含字母、数字、短横线或下划线；
• 不能是 Wasp 关键字。

例如my-first-app会被解析为应用名myFirstApp。如果目录名已存在，CLI 也会直接报错提示换名（见 ProjectDescription.hs）。

可用模板一览

OpenSaaS.sh 模板（saas）

Everything a SaaS needs! 这是为直接做 SaaS 产品设计的完整模板，自带认证、ChatGPT API、Tailwind、Stripe 支付等能力。

特性清单：Stripe Payments（支付）、OpenAI GPT API、Google Auth（Google 登录）、SendGrid（邮件发送）、Tailwind（样式）、Cron Jobs（定时任务）。

使用方式：

wasp new <project-name> -t saas

该模板规模较大，从 AvailableTemplates.hs 可以看到它并非随 CLI 打包在本地，而是作为远程模板（GhRepoReleaseArchiveTemplate）存在：创建时从wasp-lang/open-saas仓库对应 Wasp 版本的 Release 中下载template.tar.gz归档。其启动指引也相对复杂，需要先cd <project-name>/app，再依次执行wasp db start、wasp db migrate-dev、cp .env.server.example .env.server并配置环境变量，最后wasp start。

向量相似度搜索模板（embeddings）

一个用于生成 Embeddings 并对文本数据执行向量相似度搜索的模板，适合做语义检索、知识库问答等场景的起点。

特性清单：Embeddings 与向量相似度搜索、OpenAI Embeddings API、向量数据库（Pinecone）、Tailwind、全栈类型安全（Full-stack Type Safety）。

使用方式：

wasp new <project-name> -t embeddings

Todo App w/ TypeScript（todo-ts）

一个使用 TypeScript 实现、具备全栈类型安全的 Todo 应用。结构简单但麻雀虽小五脏俱全，非常适合作为学习 Wasp 的第一份模板——你可以在 examples/tutorials/TodoAppTs 看到同主题的教程项目形态（含main.wasp.ts、schema.prisma与完整src/目录）。

特性清单：Auth（用户名/密码登录）、全栈类型安全。

使用方式：

wasp new <project-name> -t todo-ts

AI 生成式 Starter（ai-generated）🤖

这是 Wasp 在 AI 时代的特色模板：用几句话描述你的应用，Wasp AI 会根据描述自动生成专属的起步工程。它使用与 https://usemage.ai/ 相同的技术，会自动生成数据模型（data model）、认证（auth）、Queries、Actions 以及 React 页面。

注意：使用该模板需要提供你自己的 OpenAI API Key。

特性清单：由 OpenAI GPT 模型生成、Auth（用户名/密码）、Queries、Actions、Pages、全栈类型安全。

模板快速选型参考

创建项目之后：启动与迁移

根据模板不同，创建后的启动步骤略有差异。以默认的basic模板为例，AvailableTemplates.hs 中声明的启动指引为：

cd <project-name> wasp db migrate-dev wasp start

即：先执行数据库迁移，再启动应用（开发模式下客户端默认运行在localhost:3000）。在 Wasp 0.14 版本的文档中对应步骤为wasp db start（启动开发数据库容器），随版本演进，wasp db migrate-dev成为更常规的迁移入口。无论哪个版本，wasp start都是拉起整个全栈应用的统一命令。

源码探秘：Starter Templates 的底层实现机制

模板系统并非简单的「拷贝文件」，waspc中用一套完整的流程保证生成的工程可直接运行。核心说明位于 waspc/data/Cli/starters/README.md，创建项目分为 3 步：

1. 拷贝骨架文件（skeleton）：先复制 waspc/data/Cli/starters/skeleton 中的公共文件（.gitignore、.npmrc、tsconfig*.json等所有模板共享的基础配置）；
2. 拷贝模板文件：再叠加所选模板自身的文件（如basic、minimal），见 waspc/data/Cli/starters 目录；
3. 替换占位符：将工程内 Wasp 文件与package.json中的占位符替换为真实项目名、版本等信息。

两阶段复制与点文件还原

在 Bundled.hs 中可以看到本地模板的复制顺序：先把skeleton目录整目录复制到项目目录，接着通过renameDotfiles把骨架中以「去点」方式存储的点文件（gitignore→.gitignore、npmrc→.npmrc）恢复前导点，最后再复制所选模板目录覆盖/叠加。骨架中存点文件不带前缀是有意为之——防止 npm 打包时剥离点文件（见 StarterTemplates.hs）。

占位符替换

Templating.hs 定义了 4 个模板占位符，在生成工程时被逐一替换：

替换对象主要是工程的main.wasp.ts（或.wasp文件）与package.json，两者分别通过findWaspFile与findUserPackageJsonFile定位。这意味着模板本身写的是「通用占位符」，最终落盘的每个项目都是名称、依赖版本完全定制化的独立工程。

远程模板与版本对齐

saas模板走的是另一条路径：GhRepoReleaseArchiveTemplate会从wasp-lang/open-saas仓库、按当前 Wasp 版本动态拼出的 Git tag（形如wasp-vX.Y-template，见 AvailableTemplates.hs）对应的 Release 下载归档，再解压出其中的app子目录作为 Wasp 项目目录。这样远程模板始终与用户使用的 Wasp 主版本保持对齐，避免模板与 CLI 版本不匹配。

模板列表随版本演进

值得注意的是，模板清单是随 Wasp 版本演进的：Wasp 0.14 的文档中提供basic、todo-ts、saas、embeddings、ai-generated五个模板；而当前仓库主分支的 AvailableTemplates.hs 中，内置模板调整为basic、minimal与远程的saas三个。查阅历史版本的 versioned docs（如 web/versioned_docs/version-0.14）即可了解各版本当时提供的模板差异。因此使用wasp new -t <template>时，请以你本地 Wasp 版本实际输出的模板列表为准。

为模板做贡献：维护者开发工作流

如果你是 Wasp 贡献者、想改进内置模板，waspc/data/Cli/starters/README.md 给出了推荐的开发流程：

1. 创建测试项目：用要修改的模板执行wasp new生成一个工程；
2. 实现改动：在该 Wasp 工程中完成你的功能修改；
3. 回写模板：确认实现满意后，把文件从工程复制回模板目录；
4. 验证模板：再次用wasp-cli从模板新建项目，确认与第 1 步创建的项目一致。

由于所有模板共享的文件都收敛在skeleton目录，遵循「先骨架后模板」的叠加规则，公共改动只需落在skeleton一处即可对所有模板生效。

小结

Wasp 的 Starter Templates 把「认证、数据库、支付、AI 能力」等高频全栈需求做成了开箱即用的工程起点：wasp new交互式选择或-t参数指定模板，一条命令即可获得可运行的项目；底层则由「骨架复制 + 模板叠加 + 占位符替换」三步机制保证每个生成项目都是完全定制、可直接wasp start启动的独立工程。无论你想快速搭建 SaaS、做向量检索原型，还是让 AI 按描述生成代码，先从选择合适的模板开始，都能显著缩短从想法到可运行应用的距离。

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