Wasp CLI 命令完全指南：从创建项目、管理数据库到部署的开发者手册（version-0.14）-创锋一号

Wasp CLI 命令完全指南：从创建项目、管理数据库到部署的开发者手册（version-0.14）

【免费下载链接】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 是一个"电池齐全"的全栈 Web 框架，其命令行工具wasp是整个开发流程的枢纽：项目创建、开发服务器、数据库迁移、构建与部署全部由这一条命令驱动。本文基于 Wasp 仓库web/versioned_docs/version-0.14/general/cli.md的 CLI 参考文档，结合waspc/cli下的 Haskell 源码实现，系统讲解 Wasp CLI 的每个命令、参数与选项，帮助你在实际项目中正确使用它，并理解其背后的命令分发与前置校验机制。

概览：wasp 命令的整体面貌

Wasp 安装完成后，即可在任意终端使用wasp命令（安装步骤见快速开始）。与大多数 CLI 工具一样，直接在终端输入不带任何参数的wasp，会打印出完整的命令清单与帮助信息：

USAGE wasp <command> [command-args] COMMANDS GENERAL new [<name>] [args] Creates a new Wasp project. Run it without arguments for interactive mode. OPTIONS: -t|--template <template-name> Check out the templates list here: https://github.com/wasp-lang/starters new:ai <app-name> <app-description> [<config-json>] Uses AI to create a new Wasp project just based on the app name and the description. You can do the same thing with `wasp new` interactively. Run `wasp new:ai` for more info. version Prints current version of CLI. waspls Run Wasp Language Server. Add --help to get more info. completion Prints help on bash completion. uninstall Removes Wasp from your system. IN PROJECT start Runs Wasp app in development mode, watching for file changes. start db Starts managed development database for you. db <db-cmd> [args] Executes a database command. Run 'wasp db' for more info. clean Deletes all generated code, all cached artifacts, and the node_modules dir. Wasp equivalent of 'have you tried closing and opening it again?'. build Generates full web app code, ready for deployment. Use when deploying or ejecting. deploy Deploys your Wasp app to cloud hosting providers. telemetry Prints telemetry status. deps Prints the dependencies that Wasp uses in your project. dockerfile Prints the contents of the Wasp generated Dockerfile. info Prints basic information about the current Wasp project. test Executes tests in your project. studio (experimental) GUI for inspecting your Wasp app. EXAMPLES wasp new MyApp wasp start wasp db migrate-dev

从帮助输出可以直观地看出，命令被划分为两大类：

GENERAL（通用命令）：不依赖具体项目，包括创建项目（new）、查看版本（version）、运行语言服务器（waspls）、配置 Bash 补全（completion）、卸载（uninstall）；
IN PROJECT（项目内命令）：必须在 Wasp 项目目录内执行，包括开发、数据库、构建、部署、测试等一系列操作。

这一分类在源码中也有对应体现：命令入口 waspc/cli/exe/Main.hs 负责把原始参数解析成Command.Call数据结构，再分发到各个命令处理器；Command.Call类型定义在 waspc/cli/src/Wasp/Cli/Command/Call.hs 中，可以看到New、Start、StartDb、Clean、Db、Build、Deploy、Telemetry等与帮助输出一一对应的构造子。

创建新项目：wasp new

交互式创建

不带任何参数运行wasp new，会进入交互式向导：先提示输入项目名称，再让你从多个 starter 模板中选择一个，随后 Wasp 会基于所选模板在指定目录生成项目：

$ 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是默认模板（一个带单页面的简单 starter）。创建完成后，Wasp 会提示你进入项目目录并启动数据库。

非交互式创建

如果想跳过交互环节，直接指定项目名即可使用默认模板创建：

$ wasp new MyFirstProject 🐝 --- 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

如需指定模板，可以追加-t/--template <template-name>选项，模板清单见官方 starters 仓库。

底层实现：模板如何被解析与落地

wasp new的参数解析在 waspc/cli/src/Wasp/Cli/Command/CreateNewProject/ArgumentsParser.hs 中实现，它基于optparse-applicative定义了NewProjectArgs类型：

第一个位置参数是PROJECT_NAME（可省略，省略则进入交互模式）；
--template/-t选项接收TEMPLATE_NAME（可省略，省略则用默认模板）。

实际创建流程在 waspc/cli/src/Wasp/Cli/Command/CreateNewProject.hs 中：createNewProject先通过require校验 Node.js 与 npm 环境（ValidNodeAndNpm），然后获取项目描述，调用createProjectOnDisk将模板落地到磁盘，最后执行依赖安装并打印起步指引。值得注意的一点是，如果依赖安装失败，命令不会中断，而是以黄色警告提示你稍后运行wasp install手动补装。

模板注册表定义在 waspc/cli/src/Wasp/Cli/Command/CreateNewProject/AvailableTemplates.hs 中。从当前仓库源码看，availableStarterTemplates内置了三种模板：basic（默认，BundledStarterTemplate）、minimal（单页面极简模板）、saas（从wasp-lang/open-saas仓库的 release 归档拉取）。其中basic与minimal的模板文件直接打包在仓库的 waspc/data/Cli/starters/ 目录下（包含basic/、minimal/、skeleton/三个子目录），saas则通过GhRepoReleaseArchiveTemplate从 GitHub Release 下载，其 git tag 由当前 Wasp 版本动态推导（形如wasp-vX.Y-template）。注意：CLI 帮助文档中列出的模板清单会随版本更新，请以你安装版本实际输出的列表为准。

用 AI 创建项目：wasp new:ai

wasp new:ai是 CLI 中的 AI 辅助命令，只需要提供应用名与一句应用描述（可选地带上config-json），Wasp 的 AI 能力就会为你生成初始代码：

wasp new:ai <app-name> <app-description> [<config-json>]

该命令与wasp new交互模式中的 AI 选项等价，运行wasp new:ai（不带参数）可以看到更详细的使用说明。

项目开发命令：启动、清理、构建与部署

wasp start：开发模式启动

wasp start以开发模式启动应用，它会：

自动在浏览器中打开运行中的应用页面；
监听.wasp文件与src/目录下的文件变化，改动后自动重新编译并在浏览器中即时反映；
把 Web 应用、服务端与数据库的消息统一输出到 stdout/stderr。

从源码 waspc/cli/src/Wasp/Cli/Command/Start.hs 可以看到它的完整执行链：先执行一次初始编译（compile），随后用race并发运行两条任务——一条是watch（监听 Wasp 项目源文件变化并触发重编译），另一条是启动生成后的 Web 应用（Wasp.Generator.start，它自己也会监听生成代码的变化并重启）。两者之一异常结束时命令即失败，因此正常情况下wasp start是一个"永不退出"的长驻进程。

wasp start db：托管开发数据库

wasp start db为你启动托管的开发数据库，省去自行搭建数据库或配置连接 URL 的麻烦。它足够"聪明"：会读取 Wasp 配置中指定的数据库类型，只对 PostgreSQL 真正拉起 Docker 容器；如果你用的是 SQLite，则会直接提示"无需启动"：

Nothing to do! You are all good, you are using SQLite which doesn't need to be started.

其实现见 waspc/cli/src/Wasp/Cli/Command/Start/Db.hs，值得留意的几个行为细节：

支持--db-image <IMAGE>与--db-volume-mount-path <PATH>两个选项，分别自定义数据库的 Docker 镜像与容器内数据卷挂载路径（均有默认值，见defaultPostgresDockerImageSpec）；
如果环境变量或.env.server中已存在DATABASE_URL，命令会拒绝启动并提示你先移除该变量，以免与托管数据库冲突；
数据库数据持久化在具名 Docker volume 中，启动时会打印连接 URL 与 volume 名称，方便你日后用外部工具连接或清理；
数据库端口从默认 Postgres 端口开始向上寻找第一个空闲端口，全部被占用时会报错退出。

wasp clean：一键重置

wasp clean删除所有生成代码与缓存产物（包括node_modules），如果使用 SQLite 还会连带删除 SQLite 数据库文件。它就是 Wasp 版的"重启试试"：

$ wasp clean 🐝 --- Deleting the .wasp/ directory... ------------------------------------------- ✅ --- Deleted the .wasp/ directory. ---------------------------------------------- 🐝 --- Deleting the node_modules/ directory... ------------------------------------ ✅ --- Deleted the node_modules/ directory. ---------------------------------------

从 waspc/cli/src/Wasp/Cli/Command/Clean.hs 的实现可以看出一个工程细节：node_modules会被先删除，.wasp/目录最后删除——因为项目锁（project lock）存放在.wasp/中，只有在它被删除前其他 Wasp 命令都无法对该项目执行操作。清理完成后，命令会提示你运行wasp install重新安装依赖。

wasp build：生成可部署代码

wasp build生成完整的 Web 应用代码，产物存放在.wasp/build目录，可用于部署或 eject（脱离 Wasp 自行管理代码）场景。

wasp deploy：一键云端部署

wasp deploy让你把应用快速托管到云端。在 version-0.14 时代，Wasp 官方支持 Fly.io。

wasp telemetry：查看遥测状态

wasp telemetry打印当前项目的遥测状态，输出内容类似：

$ wasp telemetry Telemetry is currently: ENABLED Telemetry cache directory: /home/user/.cache/wasp/telemetry/ Last time telemetry data was sent for this project: 2021-05-27 09:21:16.79537226 UTC Our telemetry is anonymized and very limited in its scope: check https://wasp.sh/docs/telemetry for more details.

关于遥测采集的具体范围与隐私说明，参见遥测文档。

wasp deps / wasp info / wasp studio / wasp dockerfile / wasp test

wasp deps列出 Wasp 在你项目中使用的依赖；
wasp info输出当前 Wasp 项目的基本信息；
wasp studio（实验性）以图形化方式展示你的应用结构——页面、查询、操作、数据模型等构成的图谱；
wasp dockerfile打印 Wasp 生成的 Dockerfile 内容（供部署与定制参考）；
wasp test在项目中执行测试。

数据库命令：wasp db

Wasp 提供了一整套以db开头的数据库管理命令，它们底层主要执行 Prisma 命令，但被 Wasp 封装了一层。

wasp db migrate-dev：将开发数据库与当前 schema（实体）状态同步。如果 schema 有变化，它会生成新迁移并应用所有待执行的迁移。
- --name foo选项：为迁移指定名称（例如wasp db migrate-dev --name add-user）；
- --create-only选项：只创建迁移文件而不实际应用它。
参数解析逻辑见 waspc/cli/src/Wasp/Cli/Command/Db/Migrate.hs：它逐个扫描--create-only与--name <name>，遇到未知参数会直接报错Unknown migrate arg(s): ...。迁移流程本身通过DbOps.migrateDevAndCopyToSource在生成的工程中执行迁移，再把migrations/目录从生成工程复制回源项目，保证迁移文件被纳入版本控制。
wasp db studio：打开数据库的图形化检查界面（Prisma Studio）。

为什么不要直接使用 prisma 命令

:::caution 不要直接使用prismaCLI

虽然 Wasp 使用schema.prisma文件定义数据库 schema，但你必须使用wasp db命令而非直接调用prisma。Wasp 在 Prisma 之上添加了额外功能，直接使用prisma命令可能导致意外行为，例如缺失 auth 相关的数据模型、数据库配置不正确等。

:::

这一警告背后是实际的工程约束：所有db子命令都要经过 waspc/cli/src/Wasp/Cli/Command/Db.hs 中的makeDbCommand包装——它先获取项目锁，依次校验"处于 Wasp 项目内""Wasp spec 可用""数据库连接已建立"等前置条件，并先行编译生成代码。也就是说，wasp db ...执行的是"编译生成 → 建立连接 → 调用 Prisma 操作"的完整链路，绕开它自然容易出问题。

Bash 补全

运行wasp completion并按照提示操作，即可为 Bash 配置wasp命令的自动补全。其命令清单由wasp completion:list提供，实现位于 waspc/cli/src/Wasp/Cli/Command/BashCompletion.hs。

其他命令：version 与 uninstall

wasp version

wasp version显示 CLI 当前版本：

$ wasp version 0.14.0 If you wish to install/switch to the latest version of Wasp, do: curl -sSL https://get.wasp.sh/installer.sh | sh -s If you want specific x.y.z version of Wasp, do: curl -sSL https://get.wasp.sh/installer.sh | sh -s -- -v x.y.z Check https://github.com/wasp-lang/wasp/releases for the list of valid versions, including the latest one.

安装或切换版本的脚本命令会直接打印在输出中：默认安装最新版，通过-v x.y.z指定安装特定版本。

wasp uninstall

wasp uninstall从系统中移除 Wasp，执行前会列出待删除的目录与文件并请求确认：

$ wasp uninstall 🐝 --- Uninstalling Wasp ... ------------------------------------------------------ We will remove the following directories: {home}/.local/share/wasp-lang/ {home}/.cache/wasp/ We will also remove the following files: {home}/.local/bin/wasp Are you sure you want to continue? [y/N] y ✅ --- Uninstalled Wasp -----------------------------------------------------------

注意确认提示的默认答案是N，需要输入y才会真正执行删除。

从源码理解：CLI 命令是如何被分发与执行的

理解了每个命令的用法后，再看一眼 waspc/cli/exe/Main.hs 中命令分发的整体设计，会让你的使用更得心应手：

UTF-8 与行缓冲：入口通过withUtf8处理编码，并将 stdout 设置为行缓冲，避免输出被重定向时出现"长驻命令无输出"的假象；
参数匹配：把原始参数列表逐条与new、start db、start、clean、db、build、deploy、show等模式匹配，构造Command.Call；无法识别的命令落入Unknown分支，最终打印帮助信息；
后台遥测：命令正式执行前会异步启动一个遥测发送线程（Telemetry.considerSendingData），不影响主命令的即时响应；
统一执行：每个命令通过runCommand运行，waspc/cli/src/Wasp/Cli/Command.hs 中定义了Commandmonad 与require机制——前置校验（如"处于项目目录内"InWaspProject、"Node/npm 有效"ValidNodeAndNpm、"数据库连接已建立"DbConnectionEstablished）会先执行并缓存结果，命令失败时统一输出错误标题与详情并以非零码退出。

结语

Wasp CLI 把"声明式 Wasp 文件 → 生成式全栈应用"的整套流程压缩进了十余条命令中：wasp new负责起步，wasp start/wasp db覆盖日常开发迭代，wasp build/wasp deploy打通上线路径，wasp clean兜底疑难杂症。配合 waspc/cli 源码中清晰的分发结构与前置校验逻辑，你不仅能顺畅使用它，也能在遇到异常时快速定位问题、提交有效反馈。

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

企业官网建设流程全解析