vue3-quickstart-cli/README.md

一个用于快速创建 Vue3 项目的脚手架工具。

# 🚀 vue3-quickstart-cli

> **极速 · 专业 · 插件化 · 现代化 Vue3 项目脚手架**

---

<div align="center">
  <img src="https://vuejs.org/images/logo.png" width="100" alt="Vue3 Logo" />
  <h2>一键开启你的高质量 Vue3 项目</h2>
  <p>现代前端最佳实践 · 企业级工程化 · 极致开发体验</p>
</div>

---

## ✨ 特性亮点

- ⚡ **极速启动**：一行命令，秒级生成企业级 Vue3 项目
- 🧩 **插件化架构**：主流特性（Router、Pinia、TypeScript、ESLint、SCSS、Element Plus、axios、vueuse 等）一键集成
- 🌍 **国际化支持**：中英文全流程切换，适配全球团队
- 🛠️ **工程化能力**：Commitizen、Husky、Vitest 单元测试、自动化流程全覆盖
- 🧠 **智能交互**：支持预设（Preset）、命令行参数静默生成，适配 CI/CD
- 📝 **自动文档**：自动生成高质量 README，开箱即用
- 🔥 **Vite 构建**：默认集成 Vite，极速热更与现代开发体验
- 🧑‍💻 **友好报错与升级提示**：开发无忧，持续进化

---

## 🚀 快速上手

### 1. 全局安装

```bash
npm install -g vue3-quickstart-cli
```

### 2. 交互式创建项目

```bash
vue3-quickstart-cli
```

### 3. 一键参数化创建

```bash
vue3-quickstart-cli --name my-app --features router,pinia,typescript --pm pnpm --lang zh --yes
```

### 4. 进入项目开发

```bash
cd my-app
npm install # 或 yarn/pnpm install
npm run dev # 或 yarn dev/pnpm dev
```

---

## ⚙️ 命令参数一览

| 参数                  | 说明                                   |
|----------------------|----------------------------------------|
| --name/-n            | 指定项目名称                            |
| --features           | 逗号分隔的特性列表（如 router,pinia,ts）|
| --pm                 | 指定包管理器（pnpm/yarn/npm）           |
| --registry           | 指定 npm 源                             |
| --lang               | 语言（zh/en）                           |
| --yes/--default      | 跳过所有交互，全部默认                   |
| --preset             | 使用预设                                |
| --open               | 生成后自动打开目录                      |
| --commit             | 生成后自动 git commit                   |
| --no-version-check   | 跳过版本检测                            |
| --debug              | 输出详细错误堆栈                        |
| --template, -t      | 选择模板（如 default、admin、mobile） | 否 |

---

## 🧩 插件化特性一览

| 特性             | 说明                         | 是否可选 |
|------------------|------------------------------|----------|
| Vue Router       | 路由管理                     | ✅       |
| Pinia            | 状态管理                     | ✅       |
| TypeScript       | 类型系统                     | ✅       |
| ESLint           | 代码规范检查                 | ✅       |
| SCSS             | 样式预处理                   | ✅       |
| Element Plus     | UI 组件库，自动按需引入      | ✅       |
| axios            | 网络请求库                   | ✅       |
| vueuse           | Vue 实用工具集               | ✅       |
| Commitizen       | 规范化 git 提交              | ✅       |
| Husky            | Git 钩子自动化               | ✅       |
| Vitest           | 单元测试                     | ✅       |
| Preset           | 预设复用，团队协作           | ✅       |
| 国际化           | 中英文全流程                 | ✅       |
| 自动文档         | 自动生成高质量 README        | ✅       |

---

## 🛠️ 扩展与自定义

- 所有特性均为独立生成器，支持自定义扩展（`bin/generators/` 目录下新增/修改）。
- 支持自定义模板（`template/` 目录），可根据企业需求二次开发。
- 欢迎 PR/Issue 参与共建！

---

## 🏆 推荐最佳实践

- 推荐使用 pnpm 作为包管理器，速度快、依赖更纯净。
- 项目初始化后，建议先执行 `pnpm install`，如遇依赖冲突可尝试 `pnpm update`。
- 如需自定义特性组合，建议保存为预设（Preset），团队协作更高效。
- 定期关注脚手架升级提示，保持最佳体验。

---

## 🤝 贡献指南

1. Fork 本仓库，创建新分支
2. 提交你的改动并发起 PR
3. Issue 区欢迎反馈建议与问题

---

## 🌈 预设（Preset）机制

- 支持保存和复用常用特性组合，团队协作更高效
- 通过交互或 --preset 参数选择

---

## 💡 常见问题

- **npm login 报 Public registration is not allowed？**
  > 请确保 registry 设置为 https://registry.npmjs.org/ 并用 npm 官网账号登录。
- **npm link 报 EEXIST？**
  > 先执行 npm unlink -g vue3-quickstart-cli，再 npm link。
- **发布失败/包名冲突？**
  > 更换 package.json 的 name 字段，确保唯一。
- **依赖安全警告？**
  > 可用 npm audit fix --force 升级依赖，注意兼容性。

---

## 📚 相关文档

- [Vue3 官方文档](https://cn.vuejs.org/)
- [Vite 官方文档](https://cn.vitejs.dev/)
- [Element Plus](https://element-plus.org/)
- [Pinia](https://pinia.vuejs.org/)
- [Vue Router](https://router.vuejs.org/)
- [Vitest](https://cn.vitest.dev/)

---

## 多模板支持

- 通过 `--template` 参数选择模板，如：
  ```bash
  npx vue3-quickstart-cli --template default
  npx vue3-quickstart-cli --template admin
  ```
- 支持 `template-xxx/` 目录或 `template/xxx/` 子目录。

---

<div align="center">
  <strong>如有建议或问题，欢迎提 Issue 或联系维护者！</strong>
</div>