@lx-frontend/lx-mapp

微前端应用管理工具 - 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 秒超时保护
  • 禁用交互式密码提示
  • 详细的错误提示和解决建议
  • 显示下载耗时

💡 遇到问题？ 查看 故障排查指南

安装

方式一：使用 npx（推荐，无需安装）

# 直接运行，无需安装
npx @lx-frontend/lx-mapp --help
npx @lx-frontend/lx-mapp create
npx @lx-frontend/lx-mapp nginx

# 或使用简写
npx @lx-frontend/lx-mapp mapp --help

方式二：全局安装

npm install -g @lx-frontend/lx-mapp
# 或
pnpm add -g @lx-frontend/lx-mapp

# 安装后可直接使用
lx-mapp --help
mapp --help

方式三：项目本地安装

# 在项目中安装
pnpm add -D @lx-frontend/lx-mapp

# 使用 pnpm 运行
pnpm mapp --help

使用方式

使用 npx（推荐）

# 查看帮助
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

查看帮助

pnpm mapp --help
# 或
pnpm mapp -h

查看版本

pnpm mapp --version
# 或
pnpm mapp -v

创建新 app

添加 App

交互式添加（推荐）

pnpm mapp add app

将会依次提示输入：

1. App 名称
2. Git 模板 URL（可直接回车使用默认模板）
3. 开发服务器端口号

命令行参数

# 指定 app 名称
pnpm mapp add app myapp

# 指定 app 名称和自定义模板 URL
pnpm mapp add app myapp [email protected]:user/custom-template.git

默认模板源：

• URL: [email protected]:chenfeng/merchant-frontend-app-template.git
• 子目录: apps/

添加 Package

交互式添加（推荐）

pnpm mapp add package

将会依次提示输入：

1. Package 名称（小写字母、数字、中划线）
2. Package 描述
3. 开发服务器端口号（5000-5999）

命令行参数

# 指定 package 名称
pnpm mapp add package my-utils

# 指定 package 名称和自定义模板 URL
pnpm mapp add package my-utils [email protected]:user/custom-template.git

默认模板源：

• URL: [email protected]:chenfeng/merchant-frontend-app-template.git
• 子目录: packages/

更新 nginx 配置

# 交互式更新（推荐）
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 文件中的路由配置

命令详解

mapp create - 创建新 app

工作流程：

1. 获取 App 名称

   • 验证名称格式（只能包含字母、数字和连字符）
   • 检查是否已存在同名 app

2. 获取模板 URL

   • 可通过环境变量 LX_MAPP_DEFAULT_TEMPLATE 设置默认模板
   • 支持自定义 Git 仓库

3. 克隆模板

   • 使用 git clone --depth 1 只克隆最新提交
   • 下载到临时目录 .temp-template

4. 获取端口号

   • 扫描已存在的 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. 清理

   • 删除临时目录
   • 输出下一步操作提示

mapp nginx - 更新 nginx 配置

工作流程：

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} |

命令行参数

全局选项

-h, --help     显示帮助信息
-v, --version  显示版本信息

create 命令

lx-mapp create [appName] [templateUrl]

Arguments:
  appName      App 名称（可选，未提供将交互式输入）
  templateUrl  Git 模板仓库 URL（可选，默认使用官方模板）

Examples:
  $ pnpm mapp create
  $ pnpm mapp create myapp
  $ pnpm mapp create myapp [email protected]:user/custom-template.git

nginx 命令

lx-mapp nginx [options]

Options:
  --nginx-dir <path>       指定 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

开发

安装依赖

cd packages/merchant-micro-app
pnpm install

构建

pnpm build

构建后的文件会输出到 dist 目录，代码会被压缩优化。

本地测试

# 在项目根目录运行
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

错误处理

create 命令

• [x] 验证 app 名称格式
• [x] 检查 app 是否已存在
• [x] 验证端口号范围
• [x] 检测端口冲突
• [x] Git 克隆失败时自动清理
• [x] 创建失败时自动回滚

nginx 命令

• [x] 检查 nginx 配置文件是否存在
• [x] 检查 apps 目录是否存在
• [x] 安全的配置文件更新（先验证再写入）
• [x] 更新失败时保留原配置

注意事项

通用

• 必须在项目根目录运行命令
• 使用 DEBUG=1 pnpm mapp [command] 查看详细错误信息

create 命令

1. Git 访问权限

   • 确保有模板仓库的访问权限
   • SSH key 配置正确

2. 端口选择

   • 建议使用 3000-9999 范围
   • 自动跳过已使用的端口

3. 配置更新

   • 自动更新可能失败，请检查提示信息
   • 失败时需手动更新配置文件

4. 模板要求

   • 模板必须包含 package.json
   • package.json 中的 name 格式：dos-merchant-frontend-{name}

nginx 命令

1. 路由格式

   • 只扫描非通配符、非动态参数的路由
   • 路由格式：/path 或 /path/subpath

2. 排除 app

   • 自动排除 legacy 和 template
   • 只扫描有 src/routes/routes.ts 的 app

3. 自定义目录

   • 默认使用 nginx 目录
   • 使用 --nginx-dir 参数指定自定义目录
   • 交互模式下可动态输入目录路径
   • 支持相对路径和绝对路径

4. 模板方案（推荐）

   • 创建 nginx/default.conf.template 模板文件
   • 在模板中使用 {{MICRO_ROUTES}} 占位符
   • 路由列表保存在 nginx/micro-routes.list 中
   • 生成的 nginx/default.conf 建议加入 .gitignore

5. 配置备份

   • 建议在更新前手动备份配置文件
   • 更新失败可以恢复

环境变量

• DEBUG=1 - 启用调试模式，显示详细错误堆栈
• LX_MAPP_DEFAULT_TEMPLATE - 设置默认模板 Git URL（可选）

License

ISC