pm-pro

一个支持别名和自定义包管理器的项目创建工具，类似于 npx create 和 yarn create，但提供了更强大的配置能力。

功能特性

• 🎯 支持多种包管理器: 默认使用配置的包管理器，也可以通过命令行指定，支持别名级别的包管理器配置
• 🏷️ 别名系统: 为常用的项目模板设置简短易记的别名
• 📝 默认参数: 为别名配置默认参数，减少重复输入
• 🔗 Git 仓库支持: 支持通过 Git URL 创建项目
• 📁 本地路径支持: 支持使用本地模板路径
• 🎨 交互式选择: 当不指定项目名时，显示已配置的别名列表供选择
• 🔧 参数智能识别: 自动区分包管理器参数和包的参数
• 🔄 参数兼容处理: 自动转换不同包管理器之间的参数格式
• ✅ 包管理器检测: 执行前检测包管理器是否存在，显示版本信息
• 📦 自动标记: 项目创建成功后，自动在 package.json 中添加 packageManager 字段

安装

npm install -g pm-pro

或者使用 yarn:

yarn global add pm-pro

或者使用 pnpm:

pnpm add -g pm-pro

使用方法

基本用法

# 创建项目（如果配置了别名）
pro create my-app

# 使用指定的包管理器
pro create my-app --pm yarn
# 或
pro create my-app --pm pnpm

# 传递额外参数给 create 命令
pro create my-app -- --typescript --tailwind

# 不指定项目名，显示交互式列表
pro create

配置文件

配置文件位于 ~/.procreaterc.json，首次运行时会自动创建。

配置示例

{
  "defaultPackageManager": "npm",
  "aliases": {
    "create-my-app": {
      "package": "create-next-app",
      "args": []
    },
    "create-vue-app": {
      "package": "@vue/cli",
      "args": []
    },
    "create-react-app": {
      "package": "create-react-app",
      "args": ["--template", "typescript"]
    },
    "create-next-app": {
      "package": "create-next-app",
      "args": ["--example-path", "xxx"]
    },
    "create-git-app": {
      "package": "https://github.com/user/repo.git",
      "args": []
    },
    "create-local-app": {
      "package": "/path/to/local/template",
      "args": []
    },
    "my-app": {
      "package": "my-custom-package",
      "args": ["--flag", "value"]
    }
  }
}

配置说明

• defaultPackageManager: 默认使用的包管理器，可选值: npm、yarn、pnpm
• aliases: 别名配置对象
  • key: 别名名称（例如: create-my-app）
  • value: 别名配置对象
    • package: 实际的包名、Git URL 或本地路径
    • args: 默认参数数组（可选，原封不动传递给包管理器）
    • prefer: 优先使用的包管理器（可选，如果命令行未指定则使用此值）
    • only: 强制使用的包管理器（可选，忽略命令行参数和全局配置）

包管理器优先级

包管理器的选择按以下优先级（从高到低）：

1. only（别名配置中的 only）- 如果设置，强制使用，忽略其他所有配置
2. --pm 参数（命令行参数）
3. prefer（别名配置中的 prefer）
4. defaultPackageManager（全局默认包管理器配置）
5. npm（最终默认值）

如果 only 与 --pm 冲突，会给出错误提示。

别名类型

1. npm 包（create 开头）

{
  "create-my-app": {
    "package": "create-next-app",
    "args": []
  }
}

2. npm 包（非 create 开头）

{
  "my-app": {
    "package": "my-custom-package",
    "args": []
  }
}

3. Git 仓库

{
  "create-git-app": {
    "package": "https://github.com/user/repo.git",
    "args": []
  }
}

4. 本地路径

{
  "create-local-app": {
    "package": "/absolute/path/to/template",
    "args": []
  }
}

或者使用相对路径:

{
  "create-local-app": {
    "package": "./local/template",
    "args": []
  }
}

5. 带默认参数的别名

{
  "create-next-app": {
    "package": "create-next-app",
    "args": ["--typescript", "--tailwind", "--app"]
  }
}

当使用 pro create create-next-app 时，会自动添加这些默认参数。如果用户提供了额外的参数，会追加到默认参数后面。

命令参考

创建项目

pro create [project-name] [options]

• project-name: 项目名或别名（可选）
• --pm <pm>: 指定包管理器（npm/yarn/pnpm）

包管理器管理

# 查看当前默认包管理器
pro pm show

# 设置默认包管理器
pro pm use <npm|yarn|pnpm>

示例：

pro pm show          # 显示: 当前默认包管理器: npm
pro pm use yarn      # 设置默认包管理器为 yarn
pro pm use pnpm      # 设置默认包管理器为 pnpm

别名管理

# 列出所有别名
pro alias list

# 设置/添加别名
pro alias set <alias> <package> [--args '<args>'] [--prefer <pm>] [--only <pm>]

# 更新别名
pro alias update <alias> <package> [--args '<args>'] [--prefer <pm>] [--only <pm>]

# 删除别名
pro alias delete <alias>

示例：

# 列出所有别名
pro alias list

# 添加别名（不带参数）
pro alias set create-my-app create-next-app

# 添加别名（带默认参数和包管理器偏好）
pro alias set create-next-app create-next-app --args '--typescript --tailwind' --prefer yarn

# 添加别名（强制使用特定包管理器）
pro alias set create-vue-app @vue/cli --only pnpm

# 更新别名
pro alias update create-next-app create-next-app --args '--typescript' --prefer pnpm

# 清除 prefer/only 设置
pro alias update create-next-app create-next-app --prefer ''  # 清除 prefer
pro alias update create-next-app create-next-app --only ''    # 清除 only

# 删除别名（会要求确认）
pro alias delete create-my-app

帮助命令

pro help
pro --help
pro -h

命令行选项

• --pm <pm>: 指定包管理器（npm/yarn/pnpm）
• --help, -h: 显示帮助信息
• --version, -V: 显示版本号

工作原理

1. 当执行 pro create <project-name> 时，工具会：

   • 读取配置文件 ~/.procreaterc.json
   • 检查是否存在别名映射
   • 如果存在别名，使用别名配置的包名和默认参数
   • 如果不存在别名，直接使用提供的项目名
   • 根据优先级确定使用的包管理器（only > --pm > prefer > default > npm）
   • 检测包管理器是否存在，不存在则给出友好错误提示
   • 获取包管理器版本号，在执行时显示
   • 自动识别命令行参数，区分包管理器参数和包的参数
   • 对包管理器参数进行兼容处理，转换不同包管理器之间的参数格式
   • 执行相应的命令：
     • npm: 使用 npm create <package> -- [args...]
     • yarn: 使用 yarn create <package> [args...]
     • pnpm: 使用 pnpm create <package> [args...]

2. 当只执行 pro create 时：

   • 显示已配置的别名列表
   • 用户可以选择已配置的别名，或输入其他项目名

参数处理

配置文件参数

配置文件中的 args 参数会原封不动传递给包管理器，不做任何区分或转换。

命令行参数

命令行参数会自动识别为两类：

1. 包管理器参数：如 --global, --save-dev, --registry 等

   • 这些参数会被自动识别
   • 会根据目标包管理器进行兼容转换
   • 如果无法兼容，会给出错误提示

2. 包的参数：其他所有参数

   • 原封不动传递给要创建的包

参数兼容

工具会自动转换不同包管理器之间的参数格式，例如：

• --global (npm) → global (yarn) 或 --global (pnpm)
• --save-dev (npm) → --dev (yarn) 或 --save-dev (pnpm)
• --frozen-lockfile (yarn) → 在 npm/pnpm 中不支持，会给出错误提示

如果某个参数在目标包管理器中不支持且无法转换，会给出友好的错误提示。

自动添加 packageManager 字段

项目创建成功后，工具会自动检测项目路径和 package.json 文件，并静默添加包管理器信息：

• 如果 packageManager 字段不存在：添加 packageManager 字段
• 如果 packageManager 字段已存在：添加 proPackageManager 字段

检测策略

工具使用以下策略自动检测项目路径：

1. 命令行参数：如果明确提供了项目名，直接查找对应目录
2. 目录对比：比较执行前后的目录变化，查找新创建的目录
3. 当前目录：检查当前目录的 package.json 是否为新创建的文件

示例

# 创建项目
pro create my-app

# 项目创建成功后，package.json 中会自动添加：
# {
#   "packageManager": "[email protected]"
# }

# 如果 packageManager 已存在：
# {
#   "packageManager": "[email protected]",
#   "proPackageManager": "[email protected]"
# }

静默处理

• 所有操作都是静默的，不会显示额外信息
• 如果无法找到项目或 package.json，静默跳过，不影响主流程
• 如果更新失败，静默处理，不显示错误信息

示例

示例 1: 使用别名

# 配置文件中有别名: "create-my-app" => "create-next-app"
pro create create-my-app

# 实际执行: npm create create-next-app
# 显示: 使用 npm (v10.0.0) 创建项目: create-next-app

示例 2: 指定包管理器

pro create create-next-app --pm yarn

# 实际执行: yarn create create-next-app

示例 3: 传递额外参数

pro create create-next-app -- --typescript --tailwind

# 实际执行: npm create create-next-app -- --typescript --tailwind

示例 4: 使用 Git 仓库

# 配置文件中: "create-git-app" => "https://github.com/user/repo.git"
pro create create-git-app

# 实际执行: npm create https://github.com/user/repo.git

示例 5: 交互式选择

pro create

# 显示:
# ? 请选择要创建的项目:
#   create-my-app (create-next-app)
#   create-vue-app (@vue/cli)
#   ──────────────
#   输入其他项目名...

开发

本项目使用 TypeScript 编写。

本地开发

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 链接到全局（用于测试）
npm link

项目结构

pm-pro/
├── bin/
│   └── pro.js              # CLI 入口（指向编译后的文件）
├── src/
│   ├── index.ts            # 主逻辑入口
│   ├── config.ts           # 配置文件管理
│   ├── aliases.ts          # 别名解析
│   ├── package-managers.ts # 包管理器执行
│   ├── interactive.ts      # 交互式选择
│   ├── commands/
│   │   ├── pm.ts           # 包管理器管理命令
│   │   └── alias.ts       # 别名管理命令
│   ├── project-detector.ts # 项目路径检测
│   ├── package-json-updater.ts # package.json 更新
│   ├── pm-resolver.ts     # 包管理器解析器
│   ├── args-parser.ts     # 参数识别
│   ├── pm-args-compat.ts  # 参数兼容处理
│   └── types.ts            # TypeScript 类型定义
├── dist/                   # TypeScript 编译输出
├── tsconfig.json           # TypeScript 配置
└── package.json

错误处理

• 如果配置文件格式错误，会显示错误信息并提示配置文件位置
• 如果指定的包管理器未安装，会显示友好的错误提示和安装指南
• 如果本地路径不存在，会显示错误信息
• 如果 Git 仓库无法访问，会显示网络错误
• 如果 only 与 --pm 冲突，会给出明确的错误提示
• 如果包管理器参数无法兼容转换，会给出错误提示和建议

包管理器未安装错误示例

❌ 错误: 包管理器 "yarn" 未安装

请使用以下命令安装:
  npm install -g yarn
  或
  corepack enable
  或
  访问 https://yarnpkg.com/getting-started/install 查看安装指南

• 如果别名不存在（删除/更新时），会显示错误信息

许可证

MIT