create-xavier-cli-temp

v1.1.0

Published

4 months ago

Xavier CLI 是一个用于创建项目的 CLI 工具

0High
0Medium
0Low

xaiverwang

xavier cli create

create-xavier-cli

create-xavier-cli 是一个基于 Node.js 的专属项目脚手架工具，支持快速创建 Vue + JavaScript/TypeScript 项目，通过交互式命令行简化项目初始化流程，内置模板下载、目录冲突处理、超时控制等功能。

一、核心功能与依赖模块解析

1.1 核心功能

交互式命令行：通过问答选择项目框架（Vue）和开发语言（JS/TS）
模板管理：从 Gitee 仓库拉取预设项目模板
目录处理：自动检测并处理目标目录冲突（覆盖/终止）
健壮性保障：模板下载超时控制、完整性校验、错误清理
友好提示：彩色日志、流程指引、成功/失败反馈

1.2 依赖模块说明

| 模块名 | 作用 | 关键用途 | |--------|------|----------| | commander | 命令行参数解析 | 定义 create 命令、版本号、帮助信息 | | inquirer | 交互式问答 | 获取项目名称、框架选择、语言选择、目录覆盖确认 | | fs-extra | 文件系统操作 | 目录创建、删除、文件读取（增强原生 fs） | | path | 路径处理 | 拼接项目目标路径、模板文件路径 | | git-clone | Git 仓库克隆 | 从 Gitee 拉取项目模板 | | ora | 加载动画 | 显示模板下载中、成功/失败状态 | | chalk | 彩色日志 | 区分信息类型（成功绿色、错误红色、提示青色） | | figlet | 字符画生成 | 生成 "Xavier CLI" 欢迎 Banner |

二、代码整体思路

2.1 架构分层

配置层：projectTemplates 定义模板映射（框架+语言 → Gitee 仓库地址）
工具函数层：
- handleTargetDir：处理目录冲突（覆盖/终止）
- gitCloneAsync：封装 git-clone 为 Promise 形式（支持异步/await）
- printWelcome/printEnd：输出欢迎信息和后续操作指引
核心逻辑层：
- createProject：项目创建主流程（目录检查 → 选择模板 → 下载模板 → 校验 → 清理 Git 目录）
命令注册层：
- 注册 create <app-name> 命令
- 处理无参数时的默认交互流程（直接启动问答）

2.2 项目创建流程（核心）graph TD

A[输入项目名称] --> B{目录是否存在？}
B -- 是 --> C{是否覆盖？}
C -- 否 --> D[终止流程]
C -- 是 --> E[删除原有目录]
B -- 否 --> F[选择框架（Vue）]
E --> F
F --> G[选择语言（JS/TS）]
G --> H[获取对应模板地址]
H --> I[启动加载动画，克隆模板]
I --> J{克隆超时/失败？}
J -- 是 --> K[清理临时目录，提示错误]
J -- 否 --> L{模板是否完整（含package.json）？}
L -- 否 --> K
L -- 是 --> M[删除模板中的 .git 目录]
M --> N[输出成功信息和后续操作指引]

三、使用教程

3.1 本地开发调试

环境准备
- 安装 Node.js（v14+）和 npm（v6+）
- 克隆项目代码到本地

安装依赖

# 进入项目根目录
cd create-xavier-cli
# 安装依赖
npm install

本地链接（模拟全局命令）

# 在项目根目录执行（将 cli 链接到全局）
npm link

使用命令
- 方式1：直接启动交互（无参数）
```
create-xavier-cli
```
- 方式2：指定项目名称（快速创建）
```
create-xavier-cli create my-vue-ts-app
```

交互流程示例

# 1. 输入项目名称（默认 my-app）
? 请输入项目文件夹名称（如 my-app）： my-vue-app

# 2. 选择框架
? 请选择框架 (Use arrow keys)
❯ 🌱 Vue

# 3. 选择语言
? 请选择开发语言 (Use arrow keys)
❯ 🟦 TypeScript
  🟨 JavaScript

# 4. 等待模板下载
🚀 项目模板下载中...

# 5. 成功提示
✅ 成功创建项目 my-vue-app
------------------------------
下一步操作：
  cd my-vue-app
  npm install
  npm run dev
------------------------------

3.2 项目后续操作

进入项目目录
```
cd my-vue-app
```
安装项目依赖
```
npm install
```
启动开发服务器
```
npm run dev
```

四、npm 发布完整流程

4.1 发布前准备

创建 npm 账号
- 访问 npm 官网注册账号
- 验证邮箱（必须完成，否则无法发布）

项目配置检查（package.json） 确保 package.json 包含以下关键配置（示例）：

{
  "name": "create-xavier-cli", // npm 包名（必须唯一）
  "version": "1.0.0", // 版本号（遵循语义化版本：MAJOR.MINOR.PATCH）
  "description": "Xavier 专属项目脚手架",
  "main": "index.js", // 入口文件（若用 ESModule 需配置 "type": "module"）
  "bin": {
    "create-xavier-cli": "./bin/index.js" // 全局命令映射（指向你的 CLI 入口文件）
  },
  "keywords": ["cli", "vue", "scaffold", "typescript"],
  "author": "Xavier Wang",
  "license": "MIT", // 开源协议（常用 MIT）
  "dependencies": {
    // 项目依赖（与代码中的 import 对应）
    "chalk": "^5.6.0",
    "commander": "^14.0.0",
    "figlet": "^1.8.2",
    "fs-extra": "^11.3.1",
    "git-clone": "^0.2.0",
    "inquirer": "^12.9.4",
    "ora": "^8.2.0"
  }
}

入口文件路径确认
- 代码中入口文件为 bin/index.js（需确保 package.json 的 bin 字段指向正确）
- 入口文件首行必须添加 Shebang（指定执行环境）：
```
#!/usr/bin/env node
```

4.2 发布步骤

登录 npm

# 在终端执行登录命令，按提示输入用户名、密码、邮箱
npm login

注意：若之前使用过淘宝镜像（registry=https://registry.npm.taobao.org），需先切换回官方镜像：
```
npm config set registry https://registry.npmjs.org/
```

版本号管理 每次发布前需更新版本号（遵循语义化版本规范）：

# 补丁版本（修复bug，如 1.0.0 → 1.0.1）
npm version patch

# 次要版本（新增功能，如 1.0.0 → 1.1.0）
npm version minor

# 主要版本（不兼容更新，如 1.0.0 → 2.0.0）
npm version major

执行后会自动更新 package.json 的 version 字段，并创建 Git 标签（tag）。

发布包
```
# 执行发布命令
npm publish
```
- 首次发布：若提示 "You do not have permission to publish 'create-xavier-cli'"，说明包名已被占用，需修改 package.json 的 name 字段为唯一名称（如 create-xavier-wang-cli）。
- 发布成功：可在 npm 官网搜索你的包名（如 create-xavier-cli）查看。

4.3 发布后验证

全局安装发布的包
```
npm install -g create-xavier-cli
```

执行命令测试

create-xavier-cli --version
# 输出：v1.0.0（与你发布的版本号一致）

# 测试创建项目
create-xavier-cli create test-app

4.4 后续维护（版本更新）

修改代码并提交 Git

git add .
git commit -m "feat: 新增 React 模板支持"

更新版本号

npm version minor # 新增功能用 minor

重新发布
```
npm publish
```

五、扩展指南

新增模板（如 React）

在 projectTemplates 中添加 React 模板映射：

const projectTemplates = {
  vue: { /* ... 原有配置 ... */ },
  react: {
    ts: "https://gitee.com/XavierWang2618/ReactTsScaffold.git",
    js: "https://gitee.com/XavierWang2618/ReactJsScaffold.git"
  }
};

在 inquirer 的框架选择列表中添加 React 选项：
```
{ name: '⚛️ React', value: 'react' }
```

自定义加载动画文字

修改 ora 初始化参数：

const spinner = ora('🚀 正在拉取 React 模板...').start();

添加更多命令（如 init）

通过 program.command 注册新命令：

program
  .command("init")
  .description("初始化现有项目配置")
  .action(() => {
    // 初始化逻辑
  });

六、常见问题

模板下载超时
- 原因：网络不稳定或 Gitee 仓库访问缓慢
- 解决：更换 npm 镜像（npm config set registry https://registry.npmmirror.com/）或增加超时时间（修改 setTimeout 的 30000 为 60000）。
目录覆盖后文件丢失
- 提示：覆盖操作会永久删除原有目录，请确认目录内无重要文件后再执行。
npm 发布权限不足
- 原因：包名已被他人占用
- 解决：修改 package.json 的 name 字段（如添加个人前缀 create-xavier-wang-cli）。