zh-template-cli

一个通用的CLI脚手架工具，支持从Git仓库拉取模板创建项目。

✨ 特性

• 🚀 从Git仓库快速拉取模板
• 📦 简单的模板管理
• 🎨 交互式项目创建
• ⚡️ 支持模板变量替换
• 🌍 支持多种Git平台（GitHub、GitLab、Gitee、阿里云Codeup等）

📦 安装

npm install -g zh-template-cli

🚀 快速开始

1. 添加模板

zh template add vue3 github:vitejs/vite#templates/vue
zh template add react github:vitejs/vite#templates/react
zh template add my-template https://github.com/user/template.git
zh template add aliyun codeup:company/project/repo

支持的Git地址格式：

• github:user/repo - GitHub简写
• gitlab:user/repo - GitLab简写
• gitee:user/repo - Gitee简写
• codeup:company/project/repo - 阿里云Codeup简写
• bitbucket:user/repo - Bitbucket简写
• github:user/repo#branch - 指定分支
• https://github.com/user/repo.git - 完整URL
• https://codeup.aliyun.com/xxx/yyy/zzz.git - 阿里云Codeup完整URL
• 任何其他Git平台的完整HTTPS URL

2. 查看模板列表

zh template list

3. 创建项目

# 交互式选择模板
zh create my-project

# 指定模板创建
zh create my-project -t vue3

4. 删除模板

zh template remove vue3

📖 命令详解

模板管理

添加模板

zh template add <name> <git-url>

• <name> - 模板名称（必填）
• <git-url> - Git仓库地址（必填）

示例：

# GitHub简写
zh template add vue3 github:vitejs/vite#templates/vue

# 完整URL
zh template add my-template https://github.com/user/template.git

# 阿里云Codeup简写
zh template add company-template codeup:company/project/repo

# 阿里云Codeup完整URL
zh template add aliyun-template https://codeup.aliyun.com/xxx/yyy/zzz.git

# Gitee
zh template add gitee-template gitee:user/repo

查看所有模板

zh template list

显示所有已添加的模板及其Git地址。

删除模板

zh template remove <name>

根据模板名称删除模板（需要确认）。

项目创建

创建新项目

zh create <project-name> [options]

选项：

• -t, --template <name> - 指定模板名称（可选，不指定则交互式选择）

示例：

# 交互式选择模板
zh create my-project

# 使用指定模板
zh create my-project -t vue3

功能：

• 从Git仓库下载模板
• 如果目录已存在，询问是否覆盖
• 支持模板变量替换
• 提示用户手动安装依赖

帮助命令

# 查看版本
zh --version
zh -v

# 查看帮助
zh --help
zh -h

📝 模板配置

在模板仓库根目录创建 template.json 文件，可以自定义项目创建流程：

{
  "name": "Vue3 Template",
  "version": "1.0.0",
  "description": "Vue 3 + Vite + TypeScript 模板",
  "prompts": [
    {
      "name": "projectName",
      "type": "input",
      "message": "项目名称",
      "default": "my-project"
    },
    {
      "name": "author",
      "type": "input",
      "message": "作者"
    },
    {
      "name": "features",
      "type": "checkbox",
      "message": "选择功能",
      "choices": [
        { "name": "Router", "value": "router", "checked": true },
        { "name": "Pinia", "value": "pinia", "checked": true }
      ]
    }
  ],
  "filters": {
    "src/router/**": "answers.features.includes('router')",
    "src/store/**": "answers.features.includes('pinia')"
  },
  "completeMessage": "项目创建成功！\n\n运行以下命令开始开发：\n  cd {{projectName}}\n  npm run dev"
}

模板变量

在模板文件中使用 Handlebars 语法插入变量：

package.json:

{
  "name": "{{projectName}}",
  "author": "{{author}}",
  "version": "1.0.0"
}

文件名变量：

__projectName__.config.js  →  my-project.config.js

条件过滤

使用 filters 字段根据用户选择过滤文件：

{
  "filters": {
    "src/router/**": "answers.features.includes('router')",
    "*.test.ts": "answers.needTests === true"
  }
}

🔧 本地开发

# 克隆项目
git clone https://github.com/yourusername/zh-cli.git
cd zh-cli

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 本地测试
npm link
zh --version

📄 配置文件

全局配置文件位置：~/.zhrc.json

{
  "templates": {
    "vue3": {
      "name": "vue3",
      "source": "github:vitejs/vite#templates/vue",
      "addedAt": "2025-10-29T10:30:00.000Z",
      "lastUsed": "2025-10-29T11:20:00.000Z"
    }
  }
}

💡 使用示例

创建Vue项目

# 添加Vue模板
zh template add vue3 github:vitejs/vite#templates/vue

# 创建项目
zh create my-vue-app -t vue3

# 进入项目并安装依赖
cd my-vue-app
npm install

# 运行项目
npm run dev

创建React项目

# 添加React模板
zh template add react github:vitejs/vite#templates/react

# 创建项目
zh create my-react-app -t react

# 进入项目并安装依赖
cd my-react-app
npm install

# 运行项目
npm run dev

使用自定义模板

# 添加你自己的模板
zh template add my-template https://github.com/yourusername/your-template.git

# 创建项目
zh create my-project -t my-template

🎯 完整工作流程

# 1. 添加常用模板
zh template add vue3 github:vitejs/vite#templates/vue
zh template add react github:vitejs/vite#templates/react
zh template add vanilla github:vitejs/vite#templates/vanilla

# 2. 查看所有模板
zh template list

# 3. 创建项目
zh create my-app

# 4. 选择模板（交互式）
? 选择项目模板: 
  ❯ vue3
    react
    vanilla

# 5. 项目创建完成
✓ 项目创建成功！

# 6. 安装依赖并开始开发
cd my-app
npm install
npm run dev

📚 常见问题

如何使用私有仓库？

确保你的Git凭据已配置，然后使用完整的URL：

zh template add private https://github.com/company/private-template.git

如何指定分支？

在Git地址后添加 #分支名：

# GitHub
zh template add template github:user/repo#dev

# 完整URL
zh template add template https://github.com/user/repo.git#dev

# 阿里云Codeup
zh template add template codeup:company/project/repo#develop

支持哪些Git平台？

CLI支持所有Git平台：

快速方式（推荐）：

• ✅ GitHub - github:user/repo
• ✅ GitLab - gitlab:user/repo
• ✅ Gitee - gitee:user/repo
• ✅ 阿里云Codeup - codeup:company/project/repo
• ✅ Bitbucket - bitbucket:user/repo

完整URL方式（通用）：

• ✅ 任何Git平台的HTTPS URL
• ✅ 私有仓库（需配置Git凭据）

模板下载失败怎么办？

1. 检查网络连接
2. 确认Git地址正确
3. 检查是否有权限访问该仓库

如何更新模板？

删除旧模板，重新添加：

zh template remove vue3
zh template add vue3 github:vitejs/vite#templates/vue

📜 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！