mars CLI 参考
npm 包名是 @marsquakes/cli,它安装的可执行命令是 mars。
pnpm add -g @marsquakes/cli
mars <command> [options]
命令
| 命令 | 说明 |
|---|---|
create <project-name> | 从模板创建新项目 |
update | 从模板更新构建接线,保留 apps/、docs/、.docs/、design/ |
dev | 启动开发(默认:所有已启用的端) |
build | 构建(默认:所有已启用的端) |
init | 安装依赖,然后按你的勾选校验并安装对应工具链 |
clean | 清理所有构建产物 |
除 create 外,其余命令都必须在生成的项目内部运行。CLI 会从当前目录逐级
向上查找 package.json、AGENTS.md 或 turbo.json 来定位项目根目录。
参数
| 参数 | 适用命令 | 说明 |
|---|---|---|
--template <url> | create | 使用某个 git 仓库作为模板 |
--from <path> | create | 使用本地目录作为模板 |
-n、--non-interactive | create | 直接采用默认的端选择 |
--platform <platform> | dev、build | 只处理指定的端 |
--docker | dev、build | 在 Docker 容器内运行 |
--docker | init | 声明 API 跑在容器里,从而跳过宿主机的 JDK/Maven |
--android-mode <mode> | init | Android 变体:local(模拟登录)或 api(真实登录后端) |
--lang <en|zh> | 全部 | 输出语言(默认 en) |
--help | 全部 | 显示帮助 |
mars create
mars create my-app
mars create my-app --non-interactive
mars create my-app --template https://github.com/you/template.git
mars create my-app --from ../local-template
模板解析顺序
CLI 按以下顺序确定模板来源,命中即停止:
--from <path>—— 本地目录。--template <url>—— git 仓库,使用浅克隆。- 当前目录,前提是它看起来像一个 Marsquakes 项目。这要求
package.json、AGENTS.md、turbo.json三者齐全 —— 比其他命令定位项目 根目录时的判断更严格,正是为了避免 在无关目录里执行mars create时把该目录 悄悄复制过去。 - 官方模板
https://github.com/sunquakes/marsquakes.git。
端的选择
| 端 | 分类 | 默认勾选 | 可选中 | 勾选会带来的工具链 |
|---|---|---|---|---|
web-admin | web | 是 | 是 | — |
api | api | 是 | 是 | Docker、JDK、Maven |
desktop | desktop | 否 | 是 | Rust |
web | web | 否 | 否 | — |
android | mobile | 否 | 否 | JDK、Android CLI |
ios | mobile | 否 | 否 | — |
windows | desktop | 否 | 否 | — |
linux | desktop | 否 | 否 | — |
macos | desktop | 否 | 否 | — |
最后一列才是 create 结束之后仍然生效的部分。一次勾选决定的既是哪个
apps/<name> 目录会被复制进来,也是 mars init 之后要在你机器
上探测并安装什么。所以选择界面会把这一列以 ↳ toolchain: 的形式显示在每一行旁
边,让你在勾之前就看到代价。空格表示这个端除了你已经有的 Node 和 pnpm 之外不再
需要任何东西 —— 要么它用基础工具就能构建(web、web-admin),要么它依赖的是
版本管理器装 不了的系统工具链(ios 需要 Xcode,windows 需要 MSVC,linux
需要 gcc)。
默认勾选和可选中在 platforms.json 里是两个不同的键:enabled 决定
这一项能不能被选(为 false 时会置灰并标上 [developing]),可选的 default
键决定它初始是否打勾。desktop 是目前唯一两者不同的端 —— 它是一个完整可用的
Tauri 应用,你可以主动勾上,只是不属于默认项目。不写 default 时会回退到
enabled。
--non-interactive 选中的正是上面这两个默认勾选的端。create 没有
--platform 参数,因此其他任何组合都必须走交互。交互的输入语法见
AI Agent。
而 api 正是这两个默认端之一,所以默认项目本身就需要 Docker、JDK 和 Maven ——
-n 跳过的是交互,不是安装。这条路径上 CLI 同样会打印推导出来的工具链集合,
所以即使没有任何界面可勾,后果也依然被讲明了。
未勾选的端根本不会被复制进新项目 —— 是直接跳过该目录,而不是先复制再删除。
create 具体做了什么
- 解析模板,复制除
apps/以外的全部内容。 - 只复制你勾选的那些
apps/<name>目录。 - 重写
platforms.json,让enabled与你的勾选一致。这也是让勾选在create结束后继续生效的机制 :后续每一条命令(包括mars init)都从这个文件重新推导 自己该做什么,而不是去读一份「你当时勾了什么」的记录。 - 在生成的文件中替换项目名(
package.json、AGENTS.md、platforms.json、 compose 文件等)。 - 删除模板自带的
.git,重新初始化仓库,并创建一条init: create project from template提交。
随后它会打印接下来需要执行的三条命令:
cd my-app
mars init
mars dev
这里是 mars init 而不是 pnpm install,因为安装 npm 依赖只是你的勾选所要求的
前一半工作 —— 见下文。
mars update
cd my-app
mars update
只刷新构建接线:
| 会更新 | 绝不触碰 |
|---|---|
AGENTS.md | apps/ |
turbo.json | docs/ |
pnpm-workspace.yaml | .docs/ |
platforms.json | design/ |
package.json | |
scripts/、packages/ |
被替换的文件会先备份到 .mars-update-backup。
mars dev
mars dev # 并行启动所有已启用的端
mars dev --platform web-admin
Web 相关的 workspace 通过 Turborepo 启动。原生端则走各自的工具链 —— 目前只有
android 接好了脚本(gradlew installDebug);ios、windows、linux、
macos 在原生方式下会提示“待完善”。
api 没有接 dev 脚本,而且不是 pnpm workspace 成员,所以不在 mars dev
的覆盖范围里。请用 Maven 直接跑在宿主机上:
cd apps/api && mvn -pl jeecg-module-system/jeecg-system-start -am spring-boot:run
mars build
mars build
mars build --platform web-admin
mars build --platform api --docker
build 目前实现了 web、web-admin、desktop、android。其他端会提示暂不
支持构建。
mars init
mars init # 依赖 + 你的勾选所要求的工具链
mars init --docker # 同上,但 API 跑在容器里
mars init --android-mode local # 独立 Android,模拟登录
mars init --android-mode api # Android 登录真实后端
这一步就是为 create 时的勾选付账的地方。init 读取 platforms.json,取其中已
启用端所需工具链的并集,然后按顺序处理:
-
确认 pnpm 存在,然后为整个 workspace 执行
pnpm install。你不需要自己再跑pnpm install——init是替代它,而不是跟在它后面。 -
如果启用了
android,执行gradlew --version预热 Gradle wrapper。 -
打印推导出来的集合,并说明每一项的来源:
🧰 Toolchain required by this project: Docker, JDK, Maven(derived from: API Service) -
逐个探测,每个结果打印一行 ——
✅带版本号,⚠️表示低于版本下限,❌表示没找到。 -
只安装探测结果不是
ok的那些,走三条路径之一。 -
如果启用了
android,再根据compileSdk推导并安装 Android SDK 包,同时把sdk.dir写入local.properties。
之所以有三条安装路径,是因为并非每个工具都能用同一种方式处理:
| 路径 | 工具 | 方式 |
|---|---|---|
| 版本管理器 | JDK、Maven、Rust | mise use --global <pin> |
| 官方安装器 | Android CLI | Google 自己的安装脚本,用户级,不需要管理员权限 |
| 只报告 | Docker | 打印名称并指向安装矩阵;系统服务不是版本管理器能装的东西 |
两个值得知道的结论:
- 集合会去重。
api和android都要 JDK,但只会下载一个。 init是幂等的。 它每次都从当前的platforms.json重新推导,所以手动启用 另一个端之后,做法就是再跑一次。探测为ok的工具不会被动。
--docker 的含义是「API 跑在容器里」,因此宿主机的 JDK 和 Maven 就不需要了。它
必须显式指定、绝不自动推断:文档里的默认方式是容器里只放 MySQL 和 Redis,API 本
身跑在宿主机上,所以「Docker 可用」并不能证明是哪种方式。这个开关的作用范围也是
收窄的 —— 在 api + android 的项目里只会跳过 Maven,JDK 仍然要装,因为 Gradle
跑在宿主机上。
选择 Android 变体
Android 应用提供两种变体:
local—— 独立应用,登录走内置的模拟数据,没有后端也能运行。api—— 登录调用真实的 JeecgBoot 后端(sys/login/sys/logout), 返回的 JWT 用于后续请求的鉴权。
变体直接由平台集合推导,不再询问:启用了 api 平台就应用 api 变体,缺少
api 平台就应用 local 变体。也可以通过 --android-mode local|api 显式覆盖
推导出的结果。
模式切换是幂等的,可以安全地重复执行:它只会改动三个接线位置 ——
settings.gradle.kts 中的 :core:network include、app 模块里对它的依赖,以及
拥有 AuthRepository 的 Hilt 绑定。网络层源码在两种模式下都保留在磁盘上,在
local 模式下只是被排除在构建之外。
凡是 init 装不了的东西,都会打印
.agents/skills/marsquakes-setup/references/install-matrix.md 的路径,那里有分操
作系统的安装命令和版本下限。另外,由于子进程改不了父 shell 的环境变量,安装成功后
它会提示你新开一个 shell,让工具进入 PATH。
mars clean
mars clean # 清理整个 workspace 的构建产物
Docker 模式
--docker 是为 CI 和打包准备的。日常开发是自己的代码跑在宿主机上,容器里只留
MySQL 和 Redis —— 见开始一个项目。
--docker 在不同命令下含义不同,别混起来:
| 命令 | --docker 的作用 |
|---|---|
init | 只是声明 API 将来跑在容器里,从而跳过宿主机的 JDK 和 Maven。不构建、不启动任何东西。 |
dev、build | 真的为该端构建镜像,并把你的代码放进容器里跑。 |
本节剩下的内容只讲第二种含义。给 dev 或 build 加上 --docker,CLI 会:
-
检查是否安装了 Docker。
-
从
platforms.json解析该端的目录(dir,默认apps/<platform>)。 -
按模式选择 Dockerfile 变体,并依次回退:
模式 变体顺序 devDockerfile.dev→Dockerfile.build→DockerfilebuildDockerfile.build→Dockerfile -
以仓库根目录为构建上下文,构建
marsquakes/<platform>:<mode>镜像。 -
以
marsquakes-<platform>-<mode>运行容器,web暴露 3100 端口,web-admin暴露 8807 端口,api暴露 8817 端口。
Dockerfile 的组织方式以及那些关键的基础镜像约束,见 Docker。
不安装直接运行
在模板仓库的克隆目录内:
node packages/mars-cli/bin/mars.js create my-app --from .
这是发布前验证模板改动最快的方式。