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/waspWasp 是一个电池齐全的全栈 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、卸载uninstallIN 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:aiwasp new:ai是 CLI 中的 AI 辅助命令只需要提供应用名与一句应用描述可选地带上config-jsonWasp 的 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 doesnt 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 testwasp deps列出 Wasp 在你项目中使用的依赖wasp info输出当前 Wasp 项目的基本信息wasp studio实验性以图形化方式展示你的应用结构——页面、查询、操作、数据模型等构成的图谱wasp dockerfile打印 Wasp 生成的 Dockerfile 内容供部署与定制参考wasp test在项目中执行测试。数据库命令wasp dbWasp 提供了一整套以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 与 uninstallwasp versionwasp 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 uninstallwasp 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 源码中清晰的分发结构与前置校验逻辑你不仅能顺畅使用它也能在遇到异常时快速定位问题、提交有效反馈。【免费下载链接】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），仅供参考