CLI tool for managing micro-frontend apps
> 微前端应用管理工具 - Micro-app Management Tool
- [x] 添加微前端应用（App）
- 从 Git 仓库克隆模板
- 自动从 apps 子目录获取模板
- 交互式输入或命令行参数
- 自动替换模板占位符
- 自动更新 host 配置和路由
- [x] 添加共享包（Package）
- 从 Git 仓库克隆模板
- 自动从 packages 子目录获取模板
- 端口范围 5000-5999
- 端口冲突检测
- [x] Nginx 配置管理
- 扫描路由并自动更新配置
- 支持模板方案和传统方案
- 自定义 nginx 目录
- 交互式和非交互模式
- [x] 完整的帮助和版本信息
- [x] Git 克隆优化
- 使用 Sparse Checkout 只下载需要的子目录（大幅提升速度）
- 自动尝试多个常见分支名称（master/main/develop）
- 60 秒超时保护
- 禁用交互式密码提示
- 详细的错误提示和解决建议
- 显示下载耗时
> 💡 遇到问题？ 查看 故障排查指南
``bash直接运行，无需安装
npx @lx-frontend/lx-mapp --help
npx @lx-frontend/lx-mapp create
npx @lx-frontend/lx-mapp nginx
$3
bash
npm install -g @lx-frontend/lx-mapp
或
pnpm add -g @lx-frontend/lx-mapp安装后可直接使用
lx-mapp --help
mapp --help
`$3
bash
在项目中安装
pnpm add -D @lx-frontend/lx-mapp使用 pnpm 运行
pnpm mapp --help
`使用方式
$3
bash
查看帮助
npx @lx-frontend/lx-mapp --help添加新 app
npx @lx-frontend/lx-mapp add app添加新 package
npx @lx-frontend/lx-mapp add package更新 nginx 配置
npx @lx-frontend/lx-mapp nginx
`$3
bash
pnpm mapp --help
或
pnpm mapp -h
`$3
bash
pnpm mapp --version
或
pnpm mapp -v
`$3
$3
#### 交互式添加（推荐）
bash
pnpm mapp add app
`将会依次提示输入：
1. App 名称
2. Git 模板 URL（可直接回车使用默认模板）
3. 开发服务器端口号
#### 命令行参数
bash
指定 app 名称
pnpm mapp add app myapp指定 app 名称和自定义模板 URL
pnpm mapp add app myapp git@example.com:user/custom-template.git
`默认模板源：
- URL:
- 子目录: $3
#### 交互式添加（推荐）
bash
pnpm mapp add package
`将会依次提示输入：
1. Package 名称（小写字母、数字、中划线）
2. Package 描述
3. 开发服务器端口号（5000-5999）
#### 命令行参数
bash
指定 package 名称
pnpm mapp add package my-utils指定 package 名称和自定义模板 URL
pnpm mapp add package my-utils git@example.com:user/custom-template.git
`默认模板源：
- URL:
- 子目录: $3
bash
交互式更新（推荐）
pnpm mapp nginx指定 nginx 目录
pnpm mapp nginx --nginx-dir ./custom-nginx非交互模式（使用默认值）
pnpm mapp nginx --no-interactive指定目录且非交互模式
pnpm mapp nginx --nginx-dir ./nginx --no-interactive
`自动扫描所有 app 的路由配置，检查并更新 nginx 配置。
目录配置：
- 默认使用当前目录下的
目录
- 可通过 --nginx-dir 参数指定自定义目录
- 交互模式下会提示确认或输入目录路径新方案（推荐）：
- 如果存在
nginx/default.conf.template 模板文件，将使用模板方案：
- 更新 nginx/micro-routes.list 路由列表文件
- 使用模板生成 nginx/default.conf 配置文件兼容方案：
- 如果不存在模板文件，将使用传统方案：
- 直接更新
nginx/default.conf 文件中的路由配置命令详解
$3
工作流程：
1. 获取 App 名称
- 验证名称格式（只能包含字母、数字和连字符）
- 检查是否已存在同名 app
2. 获取模板 URL
- 可通过环境变量
LX_MAPP_DEFAULT_TEMPLATE 设置默认模板
- 支持自定义 Git 仓库3. 克隆模板
- 使用
git clone --depth 1 只克隆最新提交
- 下载到临时目录 .temp-template4. 获取端口号
- 扫描已存在的 app 端口
- 验证端口范围（1-65535）
- 检测端口冲突
5. 复制和配置
- 复制模板文件到
- 替换所有占位符（项目名、端口号等）
- 跳过 、.git、dist 目录6. 更新配置
-
apps/host/vite.config.ts - 添加 remote entry
- apps/host/src/router/routes.ts - 添加路由
- .gitlab-ci.yml - 添加 CI 配置7. 清理
- 删除临时目录
- 输出下一步操作提示
$3
工作流程：
1. 检测方案
- 如果存在
nginx/default.conf.template，使用模板方案（推荐）
- 否则使用传统方案（兼容模式）2. 扫描路由
- 读取所有 app（除 legacy 和 template）的路由配置
- 提取所有路由路径
3. 检查配置
- 模板方案：读取
nginx/micro-routes.list 路由列表
- 传统方案：读取 nginx/default.conf 中的路由配置
- 比对路由是否已配置4. 显示结果
- 列出已配置和未配置的路由
- 显示统计信息
5. 确认目录
- 交互模式：提示用户确认或输入 nginx 目录
- 非交互模式：使用默认或命令行指定的目录
- 如果目录不存在，询问是否创建
6. 更新配置
- 询问用户是否更新
- 模板方案：
- 更新
nginx/micro-routes.list 路由列表文件
- 使用模板生成 nginx/default.conf 配置文件
- 传统方案：
- 直接更新 nginx/default.conf 文件中的路由配置目录结构：
`
项目根目录/
├── apps/ # 应用目录
│ ├── app1/
│ └── app2/
└── nginx/ # nginx 配置目录（可自定义）
├── default.conf.template # 配置模板（包含 {{MICRO_ROUTES}} 占位符）
├── micro-routes.list # 路由列表（自动生成）
└── default.conf # 最终配置（自动生成，建议加入 .gitignore）
占位符替换规则
| 原文本 | 替换为 |
|--------|--------|
|
| dos-merchant-frontend-{appName} |
| merchant-frontend-template | merchant-frontend-{appName} |
| apps/template | apps/{appName} |
| 'template' | '{appName}' |
| "template" | "{appName}" |
| app:template | app:{appName} |
| port: 3002 | port: {port} |
| port: 4002 | port: {hmrPort} |
| localhost:3002 | localhost:{port} |
| localhost:4002 | localhost:{hmrPort} |命令行参数
$3
`
-h, --help 显示帮助信息
-v, --version 显示版本信息
$3
lx-mapp create [appName] [templateUrl]Arguments:
appName App 名称（可选，未提供将交互式输入）
templateUrl Git 模板仓库 URL（可选，默认使用官方模板）
Examples:
$ pnpm mapp create
$ pnpm mapp create myapp
$ pnpm mapp create myapp git@example.com:user/custom-template.git
$3
lx-mapp nginx [options]Options:
--nginx-dir 指定 nginx 配置目录（相对或绝对路径）
--no-interactive 非交互模式，使用默认值
Examples:
$ pnpm mapp nginx # 交互式更新（推荐）
$ pnpm mapp nginx --nginx-dir ./nginx # 指定 nginx 目录
$ pnpm mapp nginx --no-interactive # 非交互模式
项目结构
packages/merchant-micro-app/
├── bin/
│ └── lx-mapp.js # CLI 主入口文件
├── core/ # 源码目录
│ ├── add-app.js # 创建 app 核心逻辑
│ ├── add-package.js # 创建 package 核心逻辑
│ ├── update-nginx.js # nginx 配置更新逻辑
│ ├── help.js # 帮助信息
│ ├── utils.js # 工具函数（颜色、图标）
│ ├── fs-utils.js # 文件系统操作
│ ├── prompts.js # 交互式输入
│ ├── config-updater.js # 配置文件更新
│ └── config.js # 配置信息
├── dist/ # 编译输出目录（构建后生成）
│ ├── core/ # 压缩后的核心模块
│ └── index.js # 入口文件
├── scripts/
│ └── build.js # 构建脚本
├── package.json
├── README.md
└── CHANGELOG.md
开发
$3
bash
cd packages/merchant-micro-app
pnpm install
`$3
bash
pnpm build
`构建后的文件会输出到
目录，代码会被压缩优化。$3
`bash
在项目根目录运行
node packages/merchant-micro-app/bin/lx-mapp.js --help
node packages/merchant-micro-app/bin/lx-mapp.js create
node packages/merchant-micro-app/bin/lx-mapp.js nginx
`错误处理
$3
- [x] 验证 app 名称格式
- [x] 检查 app 是否已存在
- [x] 验证端口号范围
- [x] 检测端口冲突
- [x] Git 克隆失败时自动清理
- [x] 创建失败时自动回滚
$3
- [x] 检查 nginx 配置文件是否存在
- [x] 检查 apps 目录是否存在
- [x] 安全的配置文件更新（先验证再写入）
- [x] 更新失败时保留原配置
注意事项
$3
- 必须在项目根目录运行命令
- 使用
查看详细错误信息$3
1. Git 访问权限
- 确保有模板仓库的访问权限
- SSH key 配置正确
2. 端口选择
- 建议使用 3000-9999 范围
- 自动跳过已使用的端口
3. 配置更新
- 自动更新可能失败，请检查提示信息
- 失败时需手动更新配置文件
4. 模板要求
- 模板必须包含
package.json
- 中的 name 格式：dos-merchant-frontend-{name}$3
1. 路由格式
- 只扫描非通配符、非动态参数的路由
- 路由格式：
或 /path/subpath2. 排除 app
- 自动排除
和 template
- 只扫描有 的 app3. 自定义目录
- 默认使用
nginx 目录
- 使用 --nginx-dir 参数指定自定义目录
- 交互模式下可动态输入目录路径
- 支持相对路径和绝对路径4. 模板方案（推荐）
- 创建
nginx/default.conf.template 模板文件
- 在模板中使用 {{MICRO_ROUTES}} 占位符
- 路由列表保存在 nginx/micro-routes.list 中
- 生成的 nginx/default.conf 建议加入 .gitignore5. 配置备份
- 建议在更新前手动备份配置文件
- 更新失败可以恢复
环境变量
-
- 启用调试模式，显示详细错误堆栈
- LX_MAPP_DEFAULT_TEMPLATE` - 设置默认模板 Git URL（可选）ISC