模块迁移工具

English | 中文

这是一个帮助将大型项目中的一部分代码迁移出来，形成独立小项目的工具。工具会分析入口文件（或目录）的所有依赖，并递归查找所有相关文件，然后将它们复制到新的目标目录中，保持原有的目录结构。

这个工具能够帮助开发者快速从大型项目中提取部分代码，同时保持所有依赖关系完整，对于需要将单体应用拆分为微前端或微服务架构的团队特别有用。工具设计考虑了可扩展性，可以轻松添加对新文件类型的支持或自定义依赖分析规则。

功能特点

• ✅ 分析 JavaScript/TypeScript 文件的静态依赖关系
• ✅ 分析 Vue 单文件组件的依赖
• ✅ 分析 CSS/SCSS/LESS 文件中的引用
• ✅ 自动处理相对路径导入
• ✅ 支持别名路径解析（如@/components）
• ✅ 自动检测项目配置（如 tsconfig.json 中的路径别名）
• ✅ 保持原始目录结构
• ✅ 生成依赖关系可视化报告
• ✅ 支持单文件或整个目录作为入口点

安装

# 全局安装，也可以采用npx执行
npm install -g module-migration-tool

# 或在项目中本地安装
npm install module-migration-tool --save-dev

或克隆仓库并手动安装：

# 克隆仓库
git clone <repository-url>

# 进入项目目录
cd migration-tool

# 安装依赖
npm install

# 创建全局链接（可选）
npm link

使用流程

使用该工具的基本步骤如下：

1. 指定源项目路径
2. 指定入口文件/目录
3. 指定目标路径
4. 工具会自动分析依赖并复制所有必要的文件

你可以通过命令行参数或配置文件自定义工具的行为，如指定要忽略的路径、配置别名路径映射等。

使用方法

命令行使用

npx 执行

# 基本用法
npx module-migrate --source <源目录> --entry <入口文件/目录> --target <目标目录>

当全局安装后，你可以使用 migrate 或 module-migrate 命令：

# 基本用法
module-migrate --source <源目录> --entry <入口文件/目录> --target <目标目录>

# 示例
module-migrate --source ./my-project/src --entry ./my-project/src/components/Feature --target ./new-project

如果是本地安装：

npx module-migrate --source <源目录> --entry <入口文件/目录> --target <目标目录>

直接使用 Node.js：

node src/index.js --source <源目录> --entry <入口文件/目录> --target <目标目录>

命令行参数

| 参数 | 简写 | 描述 | 默认值 | | ------------- | ---- | ----------------- | -------------- | | --source | -s | 源项目路径 | ./src | | --entry | -e | 入口文件/目录路径 | ./src/index.js | | --target | -t | 目标路径 | ./dist | | --config | -c | 配置文件路径 | - | | --no-report | - | 不生成依赖报告 | false | | --verbose | -v | 显示详细日志 | false |

使用配置文件

你可以创建一个配置文件来自定义工具行为，然后通过--config参数指定：

// migrate.config.js
module.exports = {
  // 支持的文件扩展名
  extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".css"],
  // 忽略的路径
  ignorePaths: ["node_modules", "dist", "test"],
  // 路径别名配置
  alias: {
    "@": "./src",
    "@components": "./src/components",
  },
  // 分析选项
  analysis: {
    includeCss: true,
    includeJson: false,
    includeImages: false,
  },
}

使用配置文件启动工具：

node src/index.js --config ./migrate.config.js

依赖分析报告

工具会生成一个 HTML 格式的依赖关系报告，可以直接在浏览器中打开查看。报告包含：

• 文件依赖关系图：可视化展示文件间的依赖关系
• 文件总数和依赖总数统计：快速了解项目规模
• 文件路径搜索功能：方便查找特定文件
• 依赖项展开/折叠功能：灵活浏览依赖树

架构设计

该项目采用模块化设计，主要包含以下模块：

• 分析器模块: 负责分析不同类型文件的依赖关系
  • JavaScript/TypeScript 分析器
  • CSS 分析器
  • Vue 单文件组件分析器
• 解析器模块: 负责解析各种导入路径
  • 路径解析器
  • 别名解析器
• 报告生成器: 生成可视化的依赖关系报告
• 工具函数: 文件操作、配置管理等通用功能

核心模块说明

项目由以下核心模块组成，每个模块负责特定的功能：

分析器模块 (analyzers)

• 功能: 分析不同类型文件中的依赖关系
• 核心文件:
  • jsAnalyzer.js: 分析 JavaScript/TypeScript 文件中的 import/require 语句
  • cssAnalyzer.js: 分析 CSS 文件中的 @import 和 url() 引用
  • vueAnalyzer.js: 分析 Vue 单文件组件中的依赖
  • index.js: 分析器统一入口，根据文件类型选择合适的分析器

解析器模块 (resolvers)

• 功能: 解析各种类型的导入路径
• 核心文件:
  • pathResolver.js: 处理相对路径、绝对路径解析
  • aliasResolver.js: 处理路径别名解析（如 @/components）
  • index.js: 路径解析统一入口

报告生成器 (reporters)

• 功能: 生成可视化的依赖关系报告
• 核心文件:
  • htmlReporter.js: 生成 HTML 格式的依赖图报告
  • index.js: 报告生成统一入口

工具函数 (utils)

• 功能: 提供通用功能支持
• 核心文件:
  • fileUtils.js: 文件操作工具（复制文件、确保目录存在等）
  • configUtils.js: 配置管理（合并配置、检测项目配置等）

核心逻辑模块

• migrator.js: 迁移工具核心类，协调各模块工作，实现主迁移逻辑
• index.js: 程序入口，处理命令行参数，提供用户界面

项目结构

migration-tool/
├── config/
│   └── default.js         # 默认配置
├── src/
│   ├── analyzers/         # 依赖分析模块
│   │   ├── index.js       # 分析器入口
│   │   ├── jsAnalyzer.js  # JS/TS 文件分析器
│   │   ├── cssAnalyzer.js # CSS 文件分析器
│   │   └── vueAnalyzer.js # Vue 文件分析器
│   ├── resolvers/         # 路径解析模块
│   │   ├── index.js       # 解析器入口
│   │   ├── pathResolver.js  # 基础路径解析
│   │   └── aliasResolver.js # 别名路径解析
│   ├── utils/             # 工具函数
│   │   ├── fileUtils.js   # 文件操作工具
│   │   └── configUtils.js # 配置工具
│   ├── reporters/         # 报告生成器
│   │   ├── index.js       # 报告器入口
│   │   └── htmlReporter.js # HTML 报告生成器
│   ├── migrator.js        # 迁移核心类
│   └── index.js           # 程序入口
├── test/                  # 用于测试代码
├── package.json           # 项目配置
└── README.md              # 项目说明

注意事项

• 工具主要处理相对路径和配置的别名路径导入，对于第三方库的导入会自动忽略
• 如果项目使用了特殊的路径解析策略，可能需要在配置文件中自定义别名配置
• 处理大型项目时可能需要较长时间，请耐心等待
• 对于某些复杂的动态导入或非常规的导入方式可能无法识别

开发与扩展

添加对新文件类型的支持

如果需要支持新的文件类型，可以在src/analyzers目录下创建新的分析器，实现analyzeFile方法，然后在src/analyzers/index.js中注册该分析器。

自定义报告格式

如需自定义依赖报告格式，可以修改src/reporters/htmlReporter.js文件或实现一个全新的报告生成器，例如 JSON 或 Markdown 格式。

许可证

MIT