Lowdefy 常用 CLI 命令详解
覆盖 init/dev/build/start 四条主命令与全部子命令总览，含帮助输出、实测回显、构建产物、退出码与常见错误处理。
LowdefyLowdefy低代码Node.jsMongoDB2026/10/28
Lowdefy 常用 CLI 命令详解
目标：把 Lowdefy CLI 从“装完能用”推进到“知道每条命令做什么、参数怎么传、失败时看哪里”。全文以 7.1.0 为准，覆盖
init、dev、build、start四条主命令，并给出其余命令的总览。所有命令与回显均来自 Ubuntu 22.04.5 实测（2026-10-27）。
一、环境信息
| 项目 | 取值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（x86_64） |
| Node.js | v24.22.1 |
| npm | 11.19.1 |
| pnpm | 12.15.0（由 corepack enable 提供） |
| Lowdefy CLI | 7.1.0（全局安装） |
| 实验应用目录 | /opt/lowdefy/c1 |
| 应用名 | Lowdefy C1 Lab |
| 生产服务端口 | 3005/tcp |
| 开发服务端口 | 3006/tcp（页面预览 3007/tcp） |
| 实测日期 | 2026-10-27 |
二、前置条件
- Node.js 24 及以上。Lowdefy 的 npm 包声明
engines.node为>=24。 - pnpm 可用。
init、dev、build在安装服务端依赖时会调用 pnpm，缺失会直接报错退出。 - 已全局安装 CLI，且
lowdefy在PATH中：
which lowdefy
lowdefy --version
实测回显：
/usr/bin/lowdefy
7.1.0
- 使用数据库或认证功能时，先准备好运行时密钥，例如
LOWDEFY_SECRET_MONGODB_URI与LOWDEFY_SECRET_AUTH_SECRET。CLI 本身不读取密钥文件，密钥由 shell 环境或服务管理器注入。
三、命令总览
3.1 查看根帮助
lowdefy --help | head -n 16
实测回显：
Usage: lowdefy [options] [command]
Lowdefy CLI
Options:
-v, --version output the version number
-h, --help display help for command
Commands:
agent-setup [options] Set up this project for AI coding agents
(.mcp.json, AGENTS.md, Claude Code skill).
build [options] Build a Lowdefy production app.
data Manage journey data sets (tests/data/<name>.yaml).
dev [options] Start a Lowdefy development server.
emails [options] Preview notification emails with the React Email
preview server.
命令列表较长，上面只截取前 16 行。完整列表以服务器上直接执行 lowdefy --help 的输出为准。
3.2 命令分组
| 分组 | 命令 | 用途 |
|---|---|---|
| 项目生命周期 | init、dev、build、start | 初始化、开发、构建、生产启动，本文重点 |
| 交付形态 | init-vercel、vercel-output | 生成 Vercel 部署产物 |
| 质量与测试 | test、data、journeys | 运行配置测试、管理测试数据、分析真实会话 |
| 辅助工具 | emails、agent-setup、mcp、hub | 邮件预览、AI 编码代理接入、本地开发服务管理 |
| 维护 | upgrade | 跨版本升级并应用 codemod |
data、journeys、hub 是多级命令，需再加 --help 查看子命令，例如 lowdefy data --help。
3.3 全局选项
多数子命令共享以下选项，含义一致：
| 选项 | 作用 |
|---|---|
--config-directory <dir> | 指定配置目录，默认当前工作目录；环境变量 LOWDEFY_DIRECTORY_CONFIG |
--disable-telemetry | 关闭遥测；环境变量 LOWDEFY_DISABLE_TELEMETRY |
--log-level <level> | 日志级别：error、warn、info、debug，默认 info；环境变量 LOWDEFY_LOG_LEVEL |
-h, --help | 查看该命令帮助 |
目录类参数都有对应的环境变量，在服务管理器里用环境变量比拼命令行更稳妥。
四、init：初始化项目
4.1 帮助与参数
lowdefy init --help
实测回显：
Usage: lowdefy init [options]
Initialize a Lowdefy project.
Options:
--disable-telemetry Disable telemetry. (env: LOWDEFY_DISABLE_TELEMETRY)
--log-level <level> The minimum severity of logs to show in the CLI output.
(choices: "error", "warn", "info", "debug", default:
"info", env: LOWDEFY_LOG_LEVEL)
-h, --help display help for command
init 没有位置参数，也没有目录参数，它在当前工作目录生成文件。要初始化到指定目录，先 cd 或先创建目录再进入。
4.2 实测执行
为不影响已有应用，init 在独立目录 /opt/lowdefy/my-app 演示：
mkdir -p /opt/lowdefy/my-app
cd /opt/lowdefy/my-app
lowdefy init
实测回显：
16:33:11 ∙ Running 'lowdefy init'.
16:33:11 ∙ Initializing Lowdefy project.
16:33:11 ∙ Created 'lowdefy.yaml'.
16:33:11 ∙ Created '.gitignore'.
16:33:11 ✔ Project initialized.
4.3 生成物说明
lowdefy.yaml：应用入口，包含一个welcome页面，可直接运行。.gitignore：内容为.lowdefy/**与.env，忽略构建目录与环境变量文件。
默认模板仍使用旧写法 areas。直接用 lowdefy dev 启动会看到配置警告：
16:26:08 ∙ /opt/lowdefy/my-app/lowdefy.yaml:6
16:26:08 ⚠ [ConfigWarning] Block "welcome" on page "welcome": "areas" is deprecated, use "slots".
16:26:08 ∙ /opt/lowdefy/my-app/lowdefy.yaml:19
16:26:08 ⚠ [ConfigWarning] Block "content" on page "welcome": "areas" is deprecated, use "slots".
16:26:08 ⚠ No menus found. Building default menu.
16:26:09 ✔ Built config in 655ms.
警告不影响启动。新建项目时把模板里的 areas 改为 slots，即可消除前两条提示；No menus found 表示未定义 menus，Lowdefy 会自动生成默认菜单。
五、dev：开发服务器
5.1 帮助与参数
lowdefy dev --help
实测回显：
Usage: lowdefy dev [options]
Start a Lowdefy development server.
Options:
--config-directory <config-directory> Change config directory. Default is the current working directory. (env: LOWDEFY_DIRECTORY_CONFIG)
--dev-directory <dev-directory> Change the development server directory. Default is "<config-directory>/.lowdefy/dev". (env: LOWDEFY_DIRECTORY_DEV)
--disable-telemetry Disable telemetry. (env: LOWDEFY_DISABLE_TELEMETRY)
--exit-with-pid <pid> Stop the server when the process with this id exits. For test runners and scripts that start the server.
--log-level <level> The minimum severity of logs to show in the CLI output. (choices: "error", "warn", "info", "debug", default: "info", env: LOWDEFY_LOG_LEVEL)
--mock-user [user] Start the dev server authenticated as a mock user (auth.dev.mockUser). Pass a JSON user object to set identity/roles, e.g. '{"sub":"dev","roles":["admin"]}'. Bare flag uses a default roleless user. Dev only. (env: LOWDEFY_DEV_USER)
--no-open Do not open a new tab in the default browser.
--port <port> Change the port the development server is hosted at. Default is 3000. (env: PORT)
--ref-resolver <ref-resolver-function-path> Path to a JavaScript file containing a _ref resolver function to be used as the app default _ref resolver.
--skip-plugin-checks Skip every plugin build check rule for this run. Built-in checks still run.
--watch <paths...> A list of paths to files or directories that should be watched for changes. Globs are supported. Specify each path to watch separated by spaces.
--watch-ignore <paths...> A list of paths to files or directories that should be ignored by the file watcher. Globs are supported. Specify each path to watch separated by spaces.
-h, --help display help for command
常用参数的选择建议：
--port：CLI 服务端口。默认 3000，冲突时换一个。--no-open：服务器上无图形界面时必加，否则会尝试拉起浏览器。--mock-user：跳过登录，以模拟身份调试受保护页面；只接受 JSON 对象或空标记，仅开发模式有效。--watch/--watch-ignore：默认只监听配置目录，引用目录之外的共享文件时用--watch显式加入。--config-directory：应用目录与当前工作目录不一致时使用，CI 脚本里很实用。
5.2 实测启动
cd /opt/lowdefy/c1
lowdefy dev --port 3006 --no-open
实测回显：
17:06:27 ∙ Running 'lowdefy dev'. Lowdefy app version 7.1.0.
17:06:27 ∙ Starting development server.
- Fetching @lowdefy/server-dev from npm.
17:06:29 ∙ Fetched @lowdefy/server-dev from npm.
- Installing dependencies.
17:06:30 ∙ Dependencies install successfully.
- Building config...
17:06:30 ∙ /bin/sh: 1: git: not found
17:06:31 ✔ Built config in 629ms.
17:06:31 ⚠ Mock user active - login bypassed
17:06:32 ∙ VITE v8.0.16 ready in 180 ms
17:06:32 ∙ ➜ Local: http://127.0.0.1:3007/
5.3 端口与监听
--port 3006 指定的是 CLI 服务端口，页面预览由 Vite 在前一个或下一个可用端口提供。本次实测：
netstat -lntp | grep -E '3005|3006|3007'
实测回显：
tcp 0 0 127.0.0.1:3007 0.0.0.0:* LISTEN 8634/node
tcp6 0 0 :::3005 :::* LISTEN 8327/node
tcp6 0 0 ::1:3006 :::* LISTEN 8589/node
两个端口都只监听回环地址，因此远程浏览器无法直接访问。需要在服务器上验证时，用 curl 在本机请求；要对外提供开发预览，应在前端加反向代理，或改用生产构建。
5.4 配置热更新与模拟用户
dev 监听配置文件，修改 lowdefy.yaml 或 pages/*.yaml 后会重建配置，日志出现：
- Building config...
17:23:47 ∙ /bin/sh: 1: git: not found
17:23:47 ✔ Built config in 176ms.
再次修改后重建耗时 187ms，说明热更新只重建配置，不会重复安装依赖。
auth.dev.mockUser 或 --mock-user 生效时，日志固定输出：
⚠ Mock user active - login bypassed
命令行参数的优先级高于配置文件，适合临时切换身份调试，不必改动 lowdefy.yaml。
六、build：生产构建
6.1 帮助与参数
lowdefy build --help
实测回显：
Usage: lowdefy build [options]
Build a Lowdefy production app.
Options:
--config-directory <config-directory> Change config directory. Default is the current working directory. (env: LOWDEFY_DIRECTORY_CONFIG)
--disable-telemetry Disable telemetry. (env: LOWDEFY_DISABLE_TELEMETRY)
--log-level <level> The minimum severity of logs to show in the CLI output. (choices: "error", "warn", "info", "debug", default: "info", env: LOWDEFY_LOG_LEVEL)
--no-client-build Do not run the Vite client build.
--ref-resolver <ref-resolver-function-path> Path to a JavaScript file containing a _ref resolver function to be used as the app default _ref resolver.
--server <server> Server package variant. Use "e2e" for @lowdefy/server-e2e. (choices: "e2e")
--server-directory <server-directory> Change the server directory. Default is "<config-directory>/.lowdefy/server". (env: LOWDEFY_DIRECTORY_SERVER)
--skip-plugin-checks Skip every plugin build check rule for this run. Built-in checks still run.
-h, --help display help for command
参数说明：
--no-client-build：只构建服务端与配置，跳过前端打包。适合只改服务端逻辑、想缩短构建时间的场景。--server-directory：默认输出到<配置目录>/.lowdefy/server，需要固定发布目录时改这里。--skip-plugin-checks：跳过插件级检查，内置检查仍会执行。排查问题时应保留默认行为。
6.2 实测构建
cd /opt/lowdefy/c1
lowdefy build
实测回显：
17:05:56 ∙ Running 'lowdefy build'. Lowdefy app version 7.1.0.
17:05:56 ∙ Starting build.
17:05:56 ∙ Dependencies unchanged.
- Running Lowdefy build.
17:05:56 ∙ $ node lowdefy/build.mjs
17:05:57 ∙ /bin/sh: 1: git: not found
17:05:57 ∙ Lowdefy build successful.
- Installing dependencies.
17:05:58 ∙ Dependencies install successfully.
- Running client build.
17:05:59 ∙ Client bundle size (gzip): 329.72 kB.
17:05:59 ∙ Client build successful.
17:05:59 ✔ Build successful.
构建分三段：服务端依赖、Lowdefy 配置构建、前端打包。git: not found 是构建收集版本信息时的提示，不影响结果，最后仍输出 Build successful。
6.3 构建产物结构
ls -1 /opt/lowdefy/c1/.lowdefy/server
实测回显：
LICENSE
README.md
build
client
dist
lib
lowdefy
lowdefy-build
node_modules
package.json
package.original.json
pnpm-lock.yaml
pnpm-workspace.yaml
postcss.config.cjs
public
public_default
src
vite.config.js
要点：
src/是服务端源码，入口为src/index.js。dist/与client/是前端构建产物，服务端启动时读取一次资源清单。node_modules/与锁文件让产物可以独立运行，复制到目标机后无需再装应用依赖。package.json记录产物依赖，package.original.json保留原始声明，二者不要手工改。
6.4 构建失败的定位
配置参数不合法时，build 会在配置构建阶段失败，并给出文件与行号：
17:05:32 ∙ /opt/lowdefy/c1/lowdefy.yaml:32
17:05:32 ✖ [ConfigError] Auth is configured without an authentication mechanism. Configure a login method ("emailAndPassword.enabled: true", "magicLink.enabled: true", "emailOTP.enabled: true" or "phoneNumber.enabled: true"), or an OAuth provider in "providers", or an API auth strategy in "strategies".
17:05:32 ∙ Build failed with 1 error(s). See above for details.
17:05:32 ∙ [ELIFECYCLE] Command failed with exit code 1.
17:05:32 ✖ Running Lowdefy build.
17:05:32 ✖ [Error] Lowdefy build failed.
看到 [ConfigError] 时先改配置，不要重试同一条命令；错误信息已经指出具体行号和缺失项。修完后重新 build，成功再 start。
七、start：生产启动
7.1 帮助与参数
lowdefy start --help
实测回显：
Usage: lowdefy start [options]
Start a Lowdefy production app.
Options:
--config-directory <config-directory> Change config directory. Default is the current working directory. (env: LOWDEFY_DIRECTORY_CONFIG)
--disable-telemetry Disable telemetry. (env: LOWDEFY_DISABLE_TELEMETRY)
--exit-with-pid <pid> Stop the server when the process with this id exits. For test runners and scripts that start the server.
--log-level <level> The minimum severity of logs to show in the CLI output. (choices: "error", "warn", "info", "debug", default: "info", env: LOWDEFY_LOG_LEVEL)
--port <port> Change the port the development server is hosted at. Default is 3000. (env: PORT)
--server-directory <server-directory> Change the server directory. Default is "<config-directory>/.lowdefy/server". (env: LOWDEFY_DIRECTORY_SERVER)
-h, --help display help for command
start 不构建、不监听配置变化，只运行已有的 .lowdefy/server。因此正确顺序永远是 build 在前、start 在后。
7.2 实测启动
cd /opt/lowdefy/c1
export LOWDEFY_SECRET_MONGODB_URI="mongodb://127.0.0.1:27017"
export LOWDEFY_SECRET_AUTH_SECRET="c1-auth-secret-0123456789"
lowdefy start --port 3005
实测回显：
17:06:09 ∙ Running 'lowdefy start'. Lowdefy app version 7.1.0.
17:06:09 ✔ Started server.
17:06:10 ∙ Lowdefy server listening on http://localhost:3005
17:06:10 ∙ app_name: Lowdefy C1 Lab
17:06:10 ∙ app_version: 0.1.0
17:06:10 ∙ server: lowdefy
17:06:10 ∙ port: 3005
17:06:10 ∙ lowdefy_version: 7.1.0
启动过程中还输出了认证密钥过短与未配置邮件两类警告，为聚焦启动信息此处省略，含义见 《Lowdefy 配置参数详解》 的认证章节。
启动横幅同时打印应用名、应用版本、服务类型、端口与 Lowdefy 版本，排障时先核对这五项。
7.3 生产与开发的行为差异
| 维度 | dev | start |
|---|---|---|
| 读取对象 | 源配置，实时构建 | 已构建的 .lowdefy/server |
| 配置热更新 | 支持 | 不支持 |
| 监听地址 | 回环（127.0.0.1） | 全部地址（0.0.0.0 / ::） |
| 默认端口 | 3000 | 3000 |
| 用途 | 本地开发调试 | 对外提供服务 |
本文实测中，dev 的 3006/3007 只能本机访问；start 的 3005 可从宿主机访问。这也是生产必须用 start 而不是 dev 的直接原因。
八、退出码与错误处理
8.1 未知命令
lowdefy foo
echo "exit=$?"
实测回显：
error: unknown command 'foo'
exit=1
未知命令退出码为 1，没有堆栈。脚本里应检查退出码，而不是只匹配输出文本。
8.2 重复启动开发服务器
同一应用目录只允许一个 dev 实例：
17:16:00 ✖ Error: A dev server for this app is already running (terminal, http://localhost:3006, pid 8589). Use it, or stop it first.
at checkNoRunningInstance (file:///usr/lib/node_modules/lowdefy/dist/commands/dev/checkNoRunningInstance.js:28:11)
at dev (file:///usr/lib/node_modules/lowdefy/dist/commands/dev/dev.js:21:5)
at Command.run (file:///usr/lib/node_modules/lowdefy/dist/utils/runCommand.js:33:31)
处理方式：复用现有实例，或先停掉旧进程再启动。换端口不能绕过该限制，因为锁按应用目录而不是按端口。
8.3 构建失败
build 失败时进程退出码为 1，日志包含 [ELIFECYCLE] Command failed with exit code 1 与具体 [Error]。在 CI 中应以退出码判断是否继续发布，不要用日志关键字匹配。
九、典型工作流
9.1 新项目
mkdir -p /opt/lowdefy/c1
cd /opt/lowdefy/c1
lowdefy init
lowdefy dev --port 3006 --no-open
先在开发模式把页面与请求调通，再进入构建与生产启动。
9.2 发布
cd /opt/lowdefy/c1
lowdefy build
export LOWDEFY_SECRET_MONGODB_URI="mongodb://127.0.0.1:27017"
export LOWDEFY_SECRET_AUTH_SECRET="c1-auth-secret-0123456789"
lowdefy start --port 3005
build 与 start 之间不要修改源配置；start 读的是构建产物，改了源文件也不会生效。
9.3 交给 systemd
把启动参数与环境变量固化到服务单元，避免手工登录服务器：
[Service]
User=lowdefy
WorkingDirectory=/opt/lowdefy/c1
Environment=LOWDEFY_SECRET_MONGODB_URI=mongodb://127.0.0.1:27017
Environment=LOWDEFY_SECRET_AUTH_SECRET=请替换为32位以上随机值
ExecStart=/usr/bin/lowdefy start --port 3000
Restart=on-failure
完整的 systemd 托管步骤与验证方法见 《Ubuntu 22.04 安装 Lowdefy 指南》。
9.4 升级
lowdefy upgrade --plan
lowdefy upgrade
先看升级计划，再执行。升级会修改配置并应用 codemod，执行前先备份 lowdefy.yaml 与 pages/。
十、参考链接
站内文档：
官方资料：
- Lowdefy 官方文档：
https://docs.lowdefy.com - 官方 CLI 文档：
https://docs.lowdefy.com/cli - 部署到 Node.js：
https://docs.lowdefy.com/node-server - 应用配置 Schema：
https://docs.lowdefy.com/lowdefy-schema - GitHub 仓库：
https://github.com/lowdefy/lowdefy
章节目录