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:
git@code.lixinio.com:chenfeng/merchant-frontend-app-template.git
- 子目录: apps/$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:
git@code.lixinio.com:chenfeng/merchant-frontend-app-template.git
- 子目录: packages/$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 目录
- 可通过 --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. 复制和配置
- 复制模板文件到
apps/{appName}
- 替换所有占位符(项目名、端口号等)
- 跳过 node_modules、.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-template | 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
`构建后的文件会输出到
dist 目录,代码会被压缩优化。$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
- 必须在项目根目录运行命令
- 使用
DEBUG=1 pnpm mapp [command] 查看详细错误信息$3
1. Git 访问权限
- 确保有模板仓库的访问权限
- SSH key 配置正确
2. 端口选择
- 建议使用 3000-9999 范围
- 自动跳过已使用的端口
3. 配置更新
- 自动更新可能失败,请检查提示信息
- 失败时需手动更新配置文件
4. 模板要求
- 模板必须包含
package.json
- package.json 中的 name 格式:dos-merchant-frontend-{name}$3
1. 路由格式
- 只扫描非通配符、非动态参数的路由
- 路由格式:
/path 或 /path/subpath2. 排除 app
- 自动排除
legacy 和 template
- 只扫描有 src/routes/routes.ts 的 app3. 自定义目录
- 默认使用
nginx 目录
- 使用 --nginx-dir 参数指定自定义目录
- 交互模式下可动态输入目录路径
- 支持相对路径和绝对路径4. 模板方案(推荐)
- 创建
nginx/default.conf.template 模板文件
- 在模板中使用 {{MICRO_ROUTES}} 占位符
- 路由列表保存在 nginx/micro-routes.list 中
- 生成的 nginx/default.conf 建议加入 .gitignore5. 配置备份
- 建议在更新前手动备份配置文件
- 更新失败可以恢复
环境变量
-
DEBUG=1 - 启用调试模式,显示详细错误堆栈
- LX_MAPP_DEFAULT_TEMPLATE` - 设置默认模板 Git URL(可选)ISC