使用 run-wasp-app 一键运行 Wasp 应用数据库自动化、dev/build 双模式与发布实战【免费下载链接】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 是面向 AI 时代的全栈 JS/TS 框架而wasp-app-runner是其官方发布的一个独立 CLI 工具包它把启动数据库 → 执行迁移 → 启动应用这套繁琐的前置流程自动化让你只需一条命令即可运行任何 Wasp 应用。本文以 wasp-app-runner/README.md 为主体结合该包在仓库内的完整 TypeScript 源码wasp-app-runner/src/深入讲解其 dev/build 两种模式、全部命令行参数、PostgreSQL/SQLite 数据库自动化机制、环境变量处理规则、本地开发调试方式以及发布到 npm 的完整流程。读完本文你将能熟练使用run-wasp-app在任意环境中一键拉起 Wasp 应用并理解其底层实现原理。一、Wasp Application Runner 是什么wasp-app-runner是仓库 wasp-app-runner 目录下维护的一个独立 npm 包包名wasp.sh/wasp-app-runner当前仓库package.json记录的版本为 0.0.17。它定位为一个健壮的运行脚本用于运行 Wasp 应用核心价值在于自动完成数据库的设置与迁移无需你手动启动 Docker 容器、设置DATABASE_URL、执行 Prisma 迁移。它提供两种运行模式dev模式调用wasp start以开发模式运行 Wasp 应用适合本地日常开发与热重载调试build模式先调用wasp build构建生产版本再以生产方式运行适合端到端测试与验证生产构建产物。安装该包后它会暴露一个run-wasp-app命令见 package.json 中的bin字段供你在任何 Wasp 项目目录下直接调用。二、快速开始三种安装与调用方式README 提供了三种用法覆盖从全局工具到项目内脚本再到一次性执行的不同场景。1. 全局依赖适合频繁使用npm install -g wasp.sh/wasp-app-runner run-wasp-app dev全局安装后run-wasp-app命令可直接在终端中使用。2. 本地依赖适合作为项目开发工具npm i -D wasp.sh/wasp-app-runner npx run-wasp-app dev本地安装后也可以通过npx调用。由于 npm 会把node_modules/.bin自动加入scripts的PATH你还可以把它直接写进 npm 脚本省去npx前缀。README 中的示例package.json如下{ // ... scripts: { run-dev: run-wasp-app dev, }, // ... }这样执行npm run run-dev即可启动开发模式。3. 一次性使用无需安装npx wasp.sh/wasp-app-runner devnpx会临时拉取并执行该包适合 CI 或临时环境。仓库内的examples/目录如examples/waspello、examples/kitchen-sink等中的示例应用都可在其目录下直接使用本命令运行。三、命令行参数详解run-wasp-app的完整用法为npx run-wasp-app mode [--path-to-app path] [--wasp-cli-cmd command] [--db-image image]其中mode是必填位置参数只能取dev或build。各选项说明如下来自 README选项说明示例--path-to-appWasp 应用目录路径默认../my-wasp-app--wasp-cli-cmdWasp CLI 命令默认waspwasp-cli--db-image自定义 PostgreSQL Docker 镜像默认postgrespostgis/postgis源码视角参数如何被解析这些参数在 参数解析模块 中基于commander-js/extra-typings实现mode通过new Argument(mode, ...).argRequired().choices([dev, build])声明为必填并限定取值传入其他值会直接报错--path-to-app、--wasp-cli-cmd分别带默认值.与wasp--wasp-cli-cmd的取值会被parseWaspCliCmd按空白拆分为{ cmd, args }结构这意味着你不仅可以把命令换成wasp-cli甚至可以传入带子命令前缀的写法如wasp-cli --flag拆分后的args会统一拼接在后续所有 Wasp 子命令之前--db-image被解析为可选的DockerImageName不传时在运行阶段使用默认镜像。一个重要的约束--db-image仅对 PostgreSQL 生效从 主流程 可以看到当应用数据库类型不是 PostgreSQL 时传入--db-image会被拒绝并报错退出The --db-image option is only valid when using PostgreSQL as the database.因此该选项只在 Wasp 应用使用 PostgreSQL 作为数据库时才有意义。四、内部工作流程从入口到双模式分发run-wasp-app的执行不是简单地拼一条命令而是有一套明确的准备与校验流程。入口在 主流程文件大致步骤如下依赖检查调用 依赖检查模块通过command -v docker确认系统已安装docker命令缺失则报错退出。这是数据库自动化的前提。探测应用信息调用waspInfo见 Wasp CLI 封装获取应用的appName应用名与dbType数据库类型sqlite或postgres。这里有一个版本兼容细节Wasp 0.26.0 起wasp info被wasp show spec取代所以实现会先尝试wasp show spec --json并解析 JSON 中的decls查找declType App与dbSystem字段若该命令失败说明是旧版 Wasp则回退解析wasp info的文本输出匹配Name:与Database system:行。校验数据库镜像如上一节所述非 PostgreSQL 应用禁止传--db-image。TS 规范项目自动安装依赖若应用目录下存在.wasp.ts文件即使用 TypeScript 规范的项目见 isWaspTypescriptConfigProject会先执行wasp install安装项目依赖确保后续命令可运行。按模式分发根据mode进入dev或build分支。整个流程中的日志统一由 logging 模块 输出任何一步失败都会记录Fatal error并以退出码 1 终止保证错误可观测。dev 模式设置数据库 → 迁移 → 启动dev 模式实现 依次执行三步setupDb → waspMigrateDb → waspStartsetupDb根据数据库类型准备连接信息详见下一节waspMigrateDb执行wasp db migrate-dev --name auto-migrationwaspStart最终执行wasp start启动开发服务器。为什么迁移命令要硬编码--name auto-migration在 waspCli.ts 的注释 中说明当应用没有migrations目录时Prisma 会交互式地询问迁移名称导致 runner 无限等待输入。显式指定名称Prisma 会自动为文件名加时间戳避免了这一挂起问题。所有 Wasp 子命令都会带上--path-to-app作为cwd并透传--db-image之外解析出的 CLI 参数。build 模式构建 → 设置数据库 → 启动 SMTP → 生产运行build 模式实现 的流程更完整执行wasp build构建生产产物setupDb准备数据库自动启动一个本地 SMTP 服务器用于应用邮件发送功能的端到端验证通过wasp build start运行生产构建并注入一组服务端环境变量与可选的 env 文件。从源码可以看到build 模式会额外注入const serverEnvVars: EnvVars { JWT_SECRET: some-jwt-secret, ...dbEnvVars, };即硬编码的JWT_SECRET加上数据库连接变量以--server-env JWT_SECRETsome-jwt-secret --server-env DATABASE_URL...形式传给wasp build start见 waspBuildStart。这保证生产模式下鉴权功能可正常工作。本地 SMTP 服务器MailcrabSMTP 模块 会在 build 模式下自动以 Docker 方式启动marlonb/mailcrab:latest镜像docker run --rm -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest1025端口是 SMTP 接收端口Wasp 应用可将其配置为邮件发送目标1080端口是 Mailcrab 的 Web 管理界面可在此查看收到的邮件。这为端到端测试如验证邮件验证码、密码重置邮件提供了即开即用的邮件基础设施。五、PostgreSQL 自动配置从容器到连接串README 指出 Postgres 配置详见./db/postgres.ts即仓库中的 PostgreSQL 实现。当应用使用 PostgreSQL 时脚本会自动为服务端应用设置DATABASE_URL环境变量DATABASE_URLpostgresql://postgres:devpasslocalhost:5432/postgres底层做了什么从源码看该连接串并非凭空而来而是完整的容器编排过程检查 Docker 是否运行执行docker info失败则提示 Docker is not running 并退出计算容器名通过 docker.ts 的 createAppSpecificDbContainerName容器名规则为{appName}-{pathToApp 的 MD5 前 16 位}-db小写。这样即使在同一台机器上运行多个同名 Wasp 项目数据库容器也不会冲突拉取镜像执行docker pull image启动容器执行docker run --name container -p 5432:5432 -e POSTGRES_PASSWORDdevpass --rm image端口固定映射到宿主机5432密码固定为devpass--rm保证退出后容器自动清理等待就绪循环调用docker exec container pg_isready -U postgres做健康检查最多重试 10 次、每次间隔 2 秒就绪后返回连接串超时则报 PostgreSQL did not become ready in time 并退出。常见启动错误的智能提示当容器启动失败时getExtraInfoOnPostgresStartError 会针对两种典型情况给出修复建议错误包含is already in use by container说明上一次清理失败建议手动执行docker rm -f containerName后重试错误包含port is already allocated说明宿主机5432端口被占用建议停掉占用该端口的进程后重试。自定义数据库镜像可通过--db-image覆盖默认的 PostgreSQL 镜像。README 给出的示例--db-image postgres:15 --db-image pgvector/pgvector:pg16 --db-image postgis/postgis:14-3.2需要说明的是README 表格中默认值写作postgres而当前仓库源码 postgres.ts 第 13 行 的实际默认值为postgres:18运行时应以实际安装的包版本为准。[!NOTE] 自定义镜像需满足与wasp start db相同的要求详见 Wasp 数据库文档。自定义镜像的典型价值在于扩展能力pgvector提供向量检索适用于 AI 类应用postgis提供地理空间数据类型postgres:15等版本号则用于锁定特定 PostgreSQL 大版本。SQLite 应用无需任何处理对于使用 SQLite 的 Wasp 应用SQLite 模块 直接返回空的dbEnvVars——SQLite 是嵌入式数据库不需要 Docker 容器与连接串。数据库类型的分发逻辑见 db/index.ts 的 setupDb它根据DbType枚举sqlite/postgres选择对应实现。六、环境变量处理规则dev 模式若应用根目录存在.env.server或.env.client文件wasp start会按 Wasp 的常规约定自动读取它们runner 本身不额外干预。因此开发模式下的密钥、API 地址等可照常放入这两个文件。build 模式runner 会在本地用 Docker 运行服务端容器时读取.env.server文件——这是 Wasp 默认流程通常不会做的事属于 runner 的增强行为构建客户端时不会使用.env.clientREACT_APP_API_URL被硬编码为http://localhost:3001与本地运行的服务端端口保持一致此外还会注入硬编码的JWT_SECRET见第四节。七、本地开发与调试 runner 本身如果你想在本地开发wasp-app-runner本身例如调试其行为或为其贡献代码无需全局安装直接在 wasp-app-runner 目录下运行npm install npm run start -- mode [--path-to-app path] [--wasp-cli-cmd command] [--db-image image]npm run start实际执行的是 package.json 中定义的npm run build node ./bin/index.js——先由tsc把 TypeScript 编译为 JavaScript再运行bin/index.js脚本。--之后的参数会原样透传给该脚本。八、发布新版本到 npmREADME 给出了完整的发布流程共三步。1. 更新包版本# 补丁版本bug 修复 npm version patch # 次版本新功能 npm version minor # 主版本破坏性变更 npm version major2. 登录 npm# 使用对 wasp.sh 组织有权限的账号登录 npm login3. 发布到 npm Registry# 以公开方式发布 npm publish --access public由于 package.json 配置了prepack: npm run build发布前会自动完成 TypeScript 编译确保bin/index.js是最新产物。九、总结wasp-app-runner把 Wasp 应用运行中最容易出错的环节——数据库准备、迁移执行、环境变量注入——全部封装进了一条run-wasp-app命令dev模式服务日常开发build模式配合 Mailcrab 邮件测试服务生产构建--path-to-app、--wasp-cli-cmd、--db-image三个选项覆盖了多项目、自定义 CLI、特殊数据库镜像等进阶场景。从 主流程 到 PostgreSQL 实现、Wasp CLI 封装其源码结构清晰、错误处理完善既是一个可直接使用的工具也是一个值得阅读的 TypeScript 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），仅供参考