企业官网建设流程全解析

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

本指南以 Wasp 官方 CLI 参考文档为主体，完整讲解wasp命令行工具的每一个命令、参数与选项，并结合本仓库（wasp-lang/wasp）中 CLI 的 Haskell 源码 深入剖析各命令的真实调用链与底层实现。读完本文，你将掌握从wasp new创建项目、wasp db管理数据库、wasp start开发调试，到wasp build/wasp deploy生产构建与部署的完整 CLI 工作流，并能理解每个命令背后发生了什么。

1. 命令总览：wasp 提供哪些能力

安装 Wasp 之后（安装方式见 快速开始），即可在命令行中使用wasp。直接运行不带任何参数的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> Available starter templates are: basic, minimal, saas, ai-generated. 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. build start [args] Previews the built production app locally. 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

从这份总览可以看出，Wasp CLI 的命令被划分为两大类：

• GENERAL（通用命令）：与具体项目无关，负责创建项目、管理 CLI 自身（版本、卸载、bash 补全、语言服务器）。
• IN PROJECT（项目内命令）：必须在某个 Wasp 项目目录内执行，负责开发、数据库、构建、部署、测试等日常开发循环。

从源码角度看，这份帮助文本直接定义在 CLI 入口文件 的printUsage函数中，命令的"路由表"则在main函数的参数模式匹配里（Main.hs）——每个命令字符串都被解析为Command.Call数据类型，再分发到对应的实现模块。因此，你看到的命令列表与源码实现是一一对应的，而非文档虚构。

2. 创建新项目：wasp new 的两种模式与可用模板

2.1 交互式创建

直接运行wasp new会进入交互模式，依次提示输入项目名、选择起始模板，随后基于所选模板生成指定名称的项目目录：

$ 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

2.2 非交互式创建

若想跳过交互式提示，直接用默认模板创建，只需在wasp new后面带上项目名：

$ 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>选项显式指定模板，以及wasp new:ai <app-name> <app-description> [<config-json>]子命令——仅凭应用名称和一句描述即可让 Wasp AI 生成初始代码（交互式wasp new中同样提供该选项）。

关于模板集合的版本差异：上面的交互式列表是 v0.19 文档记录的快照（basic / todo-ts / saas / embeddings / ai-generated）。而在本仓库当前的源码中，模板集合演进为 basic、minimal、saas 三类，见 AvailableTemplates.hs：basic为默认模板，内置覆盖最常见用例的示例代码；minimal仅含单个页面；saas则通过 GitHub Release 归档（wasp-lang/open-saas仓库对应wasp-v<主版本>.<次版本>-template标签）拉取完整 SaaS 样板，包含 Auth、Tailwind、Stripe 支付等。因此不同 Wasp 版本下-t可用的模板名不同，以该版本wasp帮助输出为准。

2.3 创建命令的源码级工作流

wasp new的实际实现位于 CreateNewProject.hs，其内部流程为：

1. 前置检查：require ValidNodeAndNpm，确认机器上 Node.js 与 npm 环境可用（对应Require/ValidNodeAndNpm.hs）；
2. 收集项目描述：通过obtainNewProjectDescription解析交互式输入或命令行参数；
3. 生成项目目录：按模板类型分派——本地捆绑模板走createProjectOnDiskFromBundledTemplate，GitHub Release 模板（如 saas）走createProjectOnDiskFromGhReleaseArchiveTemplate，见 CreateNewProject.hs；
4. 安装依赖：自动在项目目录执行installIO（等价于wasp install）。若失败会给出黄色警告，提示稍后在项目内手动运行wasp install；
5. 打印启动指引：按模板类型输出各自的后续步骤（basic 模板会提示wasp db migrate-dev与wasp start）。

3. 项目内核心命令：开发、清理与构建

3.1wasp start：开发模式

wasp start以开发模式启动应用：自动打开浏览器标签页，并持续监听.wasp文件与src/目录的变化，改动即时反映到浏览器；同时将 web 应用、服务端与数据库的消息统一输出到 stdout/stderr。

从 Start.hs 的实现看，其内部是一个并行双进程模型：

• 先执行一次编译（compile），生成完整应用代码；
• 进程 A：watch waspProjectDir outDir ...监听 Wasp 项目源码（含用户 JS/TS 代码）的变化，一旦变化即重新编译并重新生成应用；
• 进程 B：Wasp.Generator.start以开发模式启动生成后的 web 应用，同时监听生成代码并做热重启；
• 二者通过race并发运行，配合MVar在重编译产生新警告/错误时，等待应用输出安静后再次打印，避免警告被大量日志淹没。

wasp start还支持--client-port <port>与--server-port <port>选项手动指定客户端/服务端端口；若默认端口被占用，Wasp 会自动挑选第一个空闲端口（见AppComponentPorts.hs中的findAppComponentPorts）。

3.2wasp start db：托管开发数据库

wasp start db自动为你启动一个开发用数据库（默认通过 Docker 运行 Postgres），无需自己搭建数据库或向应用提供连接 URL。源码中还支持--db-image <image>与--db-volume-mount-path <path>选项，用于指定自定义 Docker 镜像或卷挂载路径（见 Main.hs 的帮助文本）。

3.3wasp clean：清除一切缓存产物

wasp clean删除所有生成代码与缓存产物；若使用 SQLite，还会一并删除 SQLite 数据库文件。它相当于 Wasp 版的"关掉再打开试试"（turn it off and on again）：

$ wasp clean 🐝 --- Deleting the .wasp/ directory... ------------------------------------------- ✅ --- Deleted the .wasp/ directory. ---------------------------------------------- 🐝 --- Deleting the node\_modules/ directory... ------------------------------------ ✅ --- Deleted the node\_modules/ directory. ---------------------------------------

实现层面，Clean.hs 会依次删除项目内的node_modules/与.wasp/两个目录（先删node_modules，后删.wasp——因为.wasp目录持有项目锁，删掉后其他 Wasp 命令才能重新开始工作），并在结尾提示运行wasp install重新安装依赖。注意clean会先通过withProjectLock获取项目锁，避免与并行运行的命令冲突。

3.4wasp build：生成可部署的完整应用代码

wasp build生成完整的、可直接部署的 web 应用代码，适用于部署或 eject（脱离 Wasp 自行维护代码）场景。生成结果存放在.wasp/build目录。部署相关说明见 部署简介。

3.5wasp build start：本地预览生产构建

wasp build start读取wasp build的产物并启动本地服务进行预览，用于在本地验证生产构建是否工作正常。它接受--server-env与--client-env选项，分别指定服务端与客户端的运行环境变量——这对于检查生产构建到底需要哪些环境变量、以及应用在生产配置下的行为非常有用。完整说明与示例见 Production Build Preview。

从 BuildStart.hs 的源码看，该命令会依次校验 Node/npm、确认存在生产构建产物（GeneratedAppIsProduction）、执行analyze分析应用规范，然后按"构建客户端 → 构建服务端 → 并行启动两端"的流程运行（BuildStart.hs）。

3.6wasp deploy：一键部署

wasp deploy将应用部署到云托管平台。v0.19 版本支持 Fly.io 与 Railway 两家提供商（部署逻辑位于仓库waspc/packages/deploy目录，详见 wasp-deploy 部署指南）。如果希望接入其他托管商，可以自行参考该目录贡献代码。

3.7wasp 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.

关于遥测的数据范围与关闭方式，参见 telemetry.md。值得一提的源码细节：在 Main.hs 中，遥测数据发送在线程中异步进行，命令结束后最多等待 1 秒即中止，确保遥测不影响命令本身的执行与退出。

3.8 其余项目内命令

• wasp deps：列出 Wasp 在项目中使用的依赖（含传递依赖）；
• wasp info：输出当前 Wasp 项目的基本信息；
• wasp studio：（实验性）以图形化方式展示应用的概览图，包括页面、查询、操作、数据模型等；
• wasp dockerfile：打印 Wasp 生成的 Dockerfile 内容；
• wasp test：执行项目中的测试。

4. 数据库命令：wasp db 全家族

Wasp 提供一套以db开头的数据库管理命令。这些命令在底层主要执行 Prisma 命令，但请务必通过wasp db使用（详见下文警告）。

4.1wasp db migrate-dev：同步数据库与实体 schema

wasp db migrate-dev将开发数据库与当前 schema（实体定义）同步：

• 若 schema 有变化，会生成新的迁移文件；
• 将待应用的迁移全部应用到数据库。

可选参数：

• --name foo：为迁移指定名称（例如wasp db migrate-dev --name "Added User entity"）；
• --create-only：仅创建空迁移文件而不应用。

从 Migrate.hs 的parseMigrateArgs可以看到这两个参数的解析方式：--create-only将_isCreateOnlyMigration置为True，--name将后续参数作为_migrationName。命令先通过migrateDevAndCopyToSource在生成的工程中执行迁移，再把迁移目录从生成代码复制回源码项目的migrations/目录——这正是 Wasp 对 Prisma 行为的关键增强之一。

4.2wasp db studio：数据库图形界面

wasp db studio打开数据库的 GUI 检视工具，方便直观查看各表数据。此外在wasp db命名空间下，当前源码还支持start（即wasp start db的别名）、reset（清空数据并重放所有迁移）与seed [name]（执行通过app.db.seeds声明的种子函数，多个种子时可指定名称，否则交互式询问），完整命令表见 Main.hs 的dbCli分发逻辑。

4.3 重要警告：不要直接使用prisma命令

:::caution 使用prismaCLI 直接操作的风险

虽然 Wasp 使用schema.prisma文件定义数据库 schema，但严禁直接使用prisma命令，必须使用wasp db系列命令。Wasp 在 Prisma 之上增加了额外功能，直接使用prisma命令可能导致意外行为，例如缺失 auth 模型、数据库配置错误等。

:::

5. Bash 补全与其他杂项命令

5.1 Bash Completion

运行wasp completion并按提示操作即可为wasp命令配置 bash 自动补全；当前源码中还提供completion:list子命令输出完整的命令列表（见 BashCompletion.hs）。

5.2wasp 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.

5.3wasp 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 -----------------------------------------------------------

6. 当前仓库中额外提供的命令

除了 v0.19 文档记录的命令，当前仓库的 CLI 源码还包含以下命令（以本仓库 Main.hs 实际路由为准，版本之间会有差异）：

• wasp doctor：检查本机是否满足 Wasp 运行要求（Node.js、Docker、端口占用等），非常适合环境排障；
• wasp compile：只编译 Wasp 项目并报告错误，不运行应用，适合 CI 中做快速校验；
• wasp install：安装 Wasp 内部依赖并执行npm install（wasp new失败时可手动补救）；
• wasp show spec [--json]/wasp show build [--json]：分别打印应用规范（路由、页面、查询、操作等）与当前构建信息的概览；
• wasp news：读取 Wasp 最新动态（仅在wasp start中周期性检查，避免打扰 CI 等其他场景，见 Start.hs 的注释说明）。

7. 一个完整的 CLI 工作流

将上述命令串联起来，一个典型的 Wasp 开发到部署循环如下：

1. 创建项目：wasp new MyApp（或交互式选择模板）；
2. 启动数据库：cd MyApp && wasp start db（开发数据库常驻运行）；
3. 应用迁移：wasp db migrate-dev --name "Init"或wasp db migrate-dev --create-only后手工编辑迁移文件；
4. 开发调试：wasp start（监听改动热更新；必要时用--client-port/--server-port指定端口）；
5. 检查依赖与状态：wasp deps、wasp info、wasp show spec；
6. 生产构建与预览：wasp build生成.wasp/build产物，wasp build start --server-env ... --client-env ...在本地验证生产行为；
7. 部署：wasp deploy一键发布到 Fly.io 或 Railway。

遇到疑难杂症时，wasp clean重置一切缓存产物，再wasp install重建依赖，往往就能解决大部分"玄学"问题——这正是 Wasp CLI 设计者给出的官方调试建议。

8. 延伸阅读

• CLI 命令入口源码：查看完整命令路由与帮助文本定义
• 创建项目命令实现 与 模板定义
• wasp start 实现 与 wasp clean 实现
• wasp db migrate-dev 实现
• wasp build start 实现
• 仓库中的真实示例项目（如 ask-the-documents、kitchen-sink、waspello）可作为wasp new生成结果的参照；仓库waspc/e2e-tests/下的WaspNewTest.hs、WaspStartTest.hs、WaspDbMigrateDevTest.hs等测试文件则是对这些命令行为最直接的验证用例。
• 快速开始 与 部署简介

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