mod_max

mod_max 是一个源码级模块管理器。

它不是安装 npm 包，而是从 Git 仓库临时拉取指定目录的源码，再复制到当前项目的指定位置。安装后的代码就是普通源码，可以在业务项目中继续二次修改。

适合管理这些不方便发布成库、但又经常复用的代码：

• request
• 表单
• 富文本
• 图标
• 弹出层
• 预览
• 表格

安装

npm i -g mod_max

安装后会得到全局命令：

mod

命令

mod i
mod u

| 命令 | 说明 | |---|---| | mod i | 安装 mod.json 中声明的模块。本地路径已存在时默认不覆盖。 | | mod u | 根据远程源码 hash、lock hash 和本地 hash 判断是否更新模块。 |

快速开始

在你的项目根目录创建 mod.json，内容按 JSON5 解析，因此可以写注释和尾逗号：

{
  // 是否允许覆盖本地已有内容
  "force": false,
  "list": [
    {
      "url": "https://github.com/your-name/shared-modules.git",
      "mod": [
        {
          "path": "src/request",
          "gitPath": "request"
        },
        {
          "path": "src/components/table",
          "gitPath": "components/table",
          "force": false,
          "cmd": [
            "npm run build"
          ]
        }
      ]
    }
  ]
}

执行安装：

mod i

安装后会生成：

mod.lock.json

后续远程模块更新后，在项目根目录执行：

mod u

完整示范

假设远程 Git 仓库结构如下：

shared-modules/
├── request/
│   └── index.ts
├── form/
│   └── index.ts
└── table/
    └── index.ts

你的业务项目希望安装：

request  ->  src/request
form     ->  src/components/form

可以在业务项目根目录创建：

{
  "force": false,
  "list": [
    {
      "url": "https://github.com/your-name/shared-modules.git",
      "mod": [
        {
          "path": "src/request",
          "gitPath": "request"
        },
        {
          "path": "src/components/form",
          "gitPath": "form",
          "cmd": [
            "npm run lint",
            "npm run build"
          ]
        }
      ]
    }
  ]
}

执行：

mod i

结果：

your-project/
├── mod.json
├── mod.lock.json
└── src/
    ├── request/
    │   └── index.ts
    └── components/
        └── form/
            └── index.ts

如果模块配置了 cmd，安装或更新成功后会先展示命令：

模块：src/components/form

需要执行以下命令，请确认没有危险操作后输入 y 再继续：

1. npm run lint
2. npm run build

是否执行当前模块的全部 cmd？(y/N)

只有输入 y 才会执行；直接回车或输入其他内容会跳过当前模块的全部命令。

安装单个文件

gitPath 可以指向 Git 仓库中的目录，也可以指向单个文件。

如果需要安装单个文件，path 写目标文件路径即可，目标文件名可以和源文件名不同：

{
  "force": false,
  "list": [
    {
      "url": "https://github.com/your-name/shared-modules.git",
      "mod": [
        {
          "path": "src/utils/req.ts",
          "gitPath": "templates/request.ts"
        }
      ]
    }
  ]
}

上面配置会把远程仓库中的 templates/request.ts 安装到当前项目的 src/utils/req.ts。

mod.json 配置说明

mod.json 支持 JSON5 语法；mod.lock.json 仍由工具生成标准 JSON。

| 字段 | 类型 | 说明 | |---|---|---| | force | boolean | 全局是否允许覆盖本地已有内容。默认 false。 | | list | array | Git 仓库列表。 | | list[].url | string | Git 仓库地址。 | | list[].mod | array | 当前 Git 仓库下要安装或更新的模块列表。 | | mod[].path | string | 模块复制到当前项目中的目标路径。 | | mod[].gitPath | string | 模块在 Git 仓库中的源码路径。 | | mod[].force | boolean | 当前模块是否允许覆盖本地已有内容。优先级高于全局 force。 | | mod[].cmd | string[] | 模块安装或更新成功后，可手动确认执行的命令列表。 |

force 规则

force 有两层：

1. 顶层 force
2. 模块级 mod[].force

最终值按下面规则计算：

effectiveForce = mod.force ?? root.force ?? false

| effectiveForce | 行为 | |---|---| | true | 允许覆盖本地已有内容。 | | false | 不覆盖，遇到已有内容或本地修改时跳过。 |

mod.lock.json

mod.lock.json 由工具自动生成，用来记录上一次成功安装、覆盖、接管或重新安装后的模块状态和 hash。

示例：

{
  "list": [
    {
      "url": "https://github.com/your-name/shared-modules.git",
      "mod": [
        {
          "path": "src/request",
          "gitPath": "request",
          "hash": "模块内容 hash"
        }
      ]
    }
  ]
}

注意：

• 执行时以 mod.json 为准。
• mod.lock.json 只记录历史状态，不主动决定安装谁。
• 如果 mod.json 删除了某个模块，mod.lock.json 中对应记录会被忽略，不会自动删除本地文件。
• 不建议手动修改 mod.lock.json。

更新逻辑简述

执行 mod u 时，每个模块会比较三个 hash：

| hash | 来源 | 作用 | |---|---|---| | oldHash | mod.lock.json | 上一次成功安装时的模块内容。 | | remoteHash | 临时 clone 后的 gitPath | 判断远程模块是否变化。 | | localHash | 当前本地 path | 判断用户是否改过本地源码。 |

基本规则：

• 远程没变化，且本地路径存在：跳过。
• 远程没变化，但本地路径被删除：重新安装。
• 远程有变化，本地没被改过：更新。
• 远程有变化，本地也被改过：根据 force 判断是否覆盖。
• 跳过时不会更新 mod.lock.json。

路径安全限制

path 和 gitPath 必须是安全的相对路径：

• 不能为空。
• 不能是绝对路径。
• 不能包含 ..。
• path 必须解析在当前项目目录内。
• gitPath 必须解析在临时 clone 的 Git 仓库目录内。

如果 gitPath 不存在，会跳过当前模块，不写入 lock，也不执行 cmd。

npm 发布说明

当前包的 npm bin 配置为：

{
  "bin": {
    "mod": "./dist/index.js"
  }
}

构建命令：

bun run build

构建后 dist/index.js 会作为 npm 全局命令入口。