脚手架模板仓库

一个可扩展的脚手架模板仓库，支持多技术栈（React、Vue、Next.js等）和多版本管理。

特性

• 🎯 按技术栈分类：清晰的组织结构，易于查找
• 📦 版本管理：每个技术栈支持多个版本/变体
• 🔧 元数据驱动：统一的 template.json 格式
• 🤖 自动化：脚本自动生成注册表，减少手动维护
• ✅ 类型安全：JSON Schema 验证模板格式
• 🚀 易于扩展：新增模板只需遵循规范即可

目录结构

template/
├── templates/              # 所有模板的根目录
│   ├── react/             # React 技术栈
│   ├── vue/               # Vue 技术栈
│   └── next/              # Next.js 技术栈
├── .templates/            # 模板管理配置
│   ├── registry.json     # 模板注册表（自动生成）
│   ├── categories.json   # 技术栈分类配置
│   └── schema.json       # template.json 的 JSON Schema
├── scripts/               # 管理脚本
│   ├── generate-registry.js
│   ├── validate-templates.js
│   └── scaffold.js
└── docs/                  # 文档

快速开始

方式一：使用 npx（推荐）

如果已发布到 npm，可以直接使用：

# 查看可用模板
npx @muliminty/template-scaffold list

# 创建项目
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]

注意：

• 由于这是作用域包，必须使用完整的作用域包名 @muliminty/template-scaffold
• 使用单个 bin 配置，可以直接运行 npx @muliminty/template-scaffold，无需额外的 -p 参数

方式二：本地开发使用

在模板仓库目录内：

# 查看可用模板
npm run scaffold:list

# 使用模板创建项目
npm run scaffold:create <template-id> <project-name> [project-path]

方式三：安装到本地使用

全局安装（推荐用于频繁使用）

将包安装到全局，可以在任何目录直接使用命令：

# 全局安装
npm install -g @muliminty/template-scaffold

# 安装后直接使用命令（注意：对于作用域包，命令名是去掉 @scope/ 后的部分）
template-scaffold list
template-scaffold create <template-id> <project-name> [project-path]


template-scaffold create next-v2-complete my-project

说明：由于使用了单个 bin 配置（"bin": "scripts/scaffold.js"），npm 会使用包名去掉作用域后的部分作为命令名，即 template-scaffold。如果希望使用完整的作用域包名，建议使用 npx @muliminty/template-scaffold。

更新全局安装的包：

npm update -g @muliminty/template-scaffold

卸载全局包：

npm uninstall -g @muliminty/template-scaffold

本地项目安装

将包作为项目依赖安装，可以在项目的 package.json scripts 中使用：

# 在项目目录中安装
npm install @muliminty/template-scaffold

# 或使用 yarn
yarn add @muliminty/template-scaffold

# 或使用 pnpm
pnpm add @muliminty/template-scaffold

安装后，可以在 package.json 的 scripts 中使用：

{
  "scripts": {
    "create:project": "template-scaffold create next-v2-complete my-project"
  }
}

注意：在 package.json 的 scripts 中使用时，如果包已安装到项目依赖中，可以直接使用 template-scaffold 命令名。也可以使用 npx @muliminty/template-scaffold。

然后运行：

npm run create:project

或者使用 npx 运行本地安装的包：

npx @muliminty/template-scaffold list
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]

方式四：使用 npx 运行本地包

在模板仓库目录外，使用 npx 运行本地包：

# 从模板仓库目录运行
npx /path/to/template/scripts/scaffold.js list
npx /path/to/template/scripts/scaffold.js create <template-id> <project-name> [project-path]

使用模板创建项目

# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]

# 或本地使用
npm run scaffold:create <template-id> <project-name> [project-path]

路径处理说明

脚手架工具支持多种路径指定方式，行为与主流脚手架工具（create-next-app、create-vite）一致：

场景 1: 在当前目录创建新文件夹（默认）

# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project
# 创建: ./my-project/ （在当前工作目录下）

场景 2: 在当前目录直接创建（不创建子文件夹）

# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project .
# 或本地使用
npm run scaffold:create next-v2-complete my-project .
# 在当前目录直接创建文件

场景 3: 指定相对路径

# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project ../my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project ../my-project
# 创建: ../my-project/ （相对于当前工作目录）

场景 4: 指定绝对路径

# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project /Users/username/projects/my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project /Users/username/projects/my-project
# 创建: /Users/username/projects/my-project/

使用示例

# 基本用法：在当前目录创建新项目
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project

# 在当前目录直接创建（不创建子文件夹）
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project .
# 或本地使用
npm run scaffold:create next-v2-complete my-project .

# 指定自定义路径
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project ~/projects/my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project ~/projects/my-project

路径验证

脚手架会自动检查：

• 目标路径是否已存在
• 目标路径是否为文件（而非目录）
• 目标目录是否为空（如果已存在且非空，会报错）

如果目标路径已存在且非空，需要先清理或选择其他位置。

管理模板

# 验证所有模板
npm run validate

# 生成模板注册表
npm run generate-registry

可用模板

运行以下命令查看所有可用模板：

# 使用 npx（如果已发布）
npx @muliminty/template-scaffold list

# 或本地使用
npm run scaffold:list

当前支持的模板：

• Next.js
  • next-v1-app-router - Next.js App Router 全栈模板
  • next-v2-complete - Next.js 完整项目模板（包含开发规范配置）

添加新模板

1. 在 templates/{技术栈}/ 下创建版本目录
2. 创建 template.json 元数据文件
3. 添加完整的项目代码
4. 运行 npm run generate-registry 更新注册表
5. 运行 npm run validate 验证模板

详细指南请参考 模板开发指南。

文档

• 架构说明 - 详细的架构设计说明
• 贡献指南 - 如何贡献新模板
• 模板开发指南 - 模板开发详细指南
• npx 使用指南 - 如何使用 npx 运行脚手架工具
• npm 发布指南 - 如何发布到 npm

命名规范

模板目录命名

格式：v{版本号}-{特性描述}

示例：

• v1-basic - 基础版本
• v2-with-router - 带路由的版本
• v1-app-router - App Router 版本

模板 ID 命名

格式：{技术栈}-v{版本号}-{特性描述}

示例：

• react-v1-basic
• vue-v2-with-pinia
• next-v1-app-router

模板变量

模板支持变量替换，在模板文件中使用 {{变量名}} 占位符：

• {{projectName}} - 项目名称
• {{projectDescription}} - 项目描述
• {{author}} - 作者信息
• {{date}} - 创建日期

在 template.json 的 variables 字段中定义自定义变量。

发布到 npm

如果你想通过 npx @muliminty/template-scaffold 使用，需要将包发布到 npm。

快速发布步骤

1. 修改 package.json：

   • 移除或设置 "private": false
   • 确保包名唯一（检查：npm view @muliminty/template-scaffold）
   • 添加作者信息
   • 添加 files 字段指定要发布的文件

2. 登录 npm：

   npm login

3. 发布：

   npm publish --access public

4. 使用：

   # 查看可用模板
   npx @muliminty/template-scaffold list
      
   # 创建项目
   npx @muliminty/template-scaffold create next-v2-complete my-project

   说明：由于使用了单个 bin 配置（"bin": "scripts/scaffold.js"），可以直接使用 npx @muliminty/template-scaffold，无需使用 -p 参数。这是作用域包使用 npx 的最佳实践。

详细发布指南请参考 npm 发布指南。

开发

安装依赖

npm install

运行脚本

# 验证模板
npm run validate

# 生成注册表
npm run generate-registry

# 列出模板
npm run scaffold:list
# 或使用 npx（如果已发布）
npx @muliminty/template-scaffold list

# 创建项目
npm run scaffold:create <template-id> <project-name> [project-path]
# 或使用 npx（如果已发布）
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]

注意：项目会创建在当前工作目录下。建议在项目父目录运行命令，而不是在模板仓库目录内。

许可证

MIT