Fast Scaff FE 项目说明

1. 项目简介

基于 Vue 3 + TypeScript + Vite + Ant Design Vue 的前端项目脚手架，提供完整的开发规范和最佳实践。你可以直接使用此项目作为模板，快速创建自己的前端项目。

2. 作为脚手架使用

2.1 快速创建新项目

方式一：使用 npx 一键创建（推荐）

项目已发布到 npm，可直接通过以下命令使用脚手架：

# 使用 npx（无需全局安装）
npx fast-scaff-fe

执行后将进入交互式流程，按提示输入「项目名称、描述、作者」等信息，脚手架会在当前目录生成新项目并自动复制所需模板文件。

方式二：克隆项目并运行初始化脚本

# 克隆或下载此项目
git clone <repository-url>

# 直接运行初始化脚本（无需进入 fast-scaff-fe 目录）
node fast-scaff-fe/scripts/init.js

2.2 初始化说明

无论使用哪种方式，脚手架脚本都会自动：

• 在当前目录创建一个新的项目文件夹
• 复制脚手架的所有文件到新项目（排除 node_modules、.git 等不需要的文件）
• 更新新项目中的 package.json 中的项目名称、描述和作者信息
• 更新新项目中的 index.html 中的页面标题

2.3 快速开始

进入新创建的项目目录后，可通过以下命令开始开发：

# 按提示输入项目信息：
# - 项目名称
# - 项目描述
# - 作者名称

# 进入新创建的项目目录
cd <your-project-name>

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

3. 技术栈

3.1 核心技术栈

| 技术 | 版本 | 用途 | | -------------- | ---- | ------------ | | Vue | 3.x | 前端框架 | | TypeScript | 5.x | 类型系统 | | Vite | 5.x | 构建工具 | | Ant Design Vue | 4.x | UI 组件库 | | Pinia | 2.x | 状态管理 | | SCSS | - | CSS 预处理器 | | Tailwind CSS | 3.x | CSS 框架 | | pnpm | 8.x+ | 包管理工具 |

3.2 技术选型原则

• 稳定性优先：选择成熟稳定的技术栈，避免使用实验性特性
• 生态完善：优先选择社区活跃、文档完善的技术方案
• 团队熟悉度：确保团队成员能够快速上手和维护
• 可维护性：代码结构清晰，易于扩展和维护

3.3 依赖管理规范

• 统一使用 pnpm 作为包管理工具，禁止混用 npm、yarn、pnpm
• 生产依赖和开发依赖分离管理
• 使用精确版本号，避免使用 ^ 或 ~ 符号
• 定期更新依赖，每季度进行一次依赖审查

4. 功能特性

• ✅ Vue 3 Composition API
• ✅ TypeScript 类型支持
• ✅ Vite 快速构建
• ✅ Ant Design Vue 组件库
• ✅ Pinia 状态管理
• ✅ Vue Router 路由管理
• ✅ Axios 请求封装
• ✅ Mock 数据支持（仅开发环境）
• ✅ ESLint + Prettier 代码规范
• ✅ Vitest 单元测试

5. 快速开始

5.1 前置要求

• Node.js >= 18.0.0
• pnpm >= 8.0.0

5.2 安装步骤

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

访问 http://localhost:3000

6. 开发命令

| 类别 | 命令 | 描述 | | ------------ | ----------------------------------------- | ------------------------------------------------------------- | | 初始化脚手架 | pnpm run init 或 node scripts/init.js | 初始化脚手架项目 | | 开发与构建 | pnpm dev | 启动本地开发服务器 | | | pnpm build | 类型检查 + 生产打包 | | | pnpm preview | 本地预览打包产物 | | 代码质量检查 | pnpm lint:check | ESLint 代码检查 | | | pnpm lint:css:check | Stylelint CSS 检查 | | | pnpm format:check | Prettier 格式检查 | | | pnpm lint | ESLint 代码修复 | | | pnpm lint:css | Stylelint CSS 修复 | | | pnpm format | Prettier 格式化 | | | pnpm check | 统一代码质量检查（门禁）： ESLint + Stylelint + Prettier | | | pnpm check:fix | 一键修复代码质量问题 | | 测试 | pnpm test | 运行单元测试 | | | pnpm test:coverage | 运行单元测试并生成覆盖率报告 |

7. AI开发规范

参考：AI开发规范

8. API接口与Mock数据规范

参考：API接口与Mock数据规范

9. 工程目录结构及命名规范

参考：工程目录结构及命名规范

10. 状态管理规范

参考：状态管理规范

11. Git 分支管理

• main：主分支，始终保持稳定可发布状态
• dev：开发分支，集成最新开发功能
• feat/*：功能分支，从 dev 分支创建
• fix/*：普通修复分支，从 dev 分支创建
• hotfix/*：线上紧急修复分支，从 main 分支创建
• release/*：发布分支，从 dev 分支创建

软件开发流程：main ←─ dev ←─ feat

以工厂生产线为例，三者的类比关系：main = 成品仓库（已测试可发货），dev = 组装线（正在测试组装），feat/* = 各个零件加工站

12. Git 提交规范

提交信息格式：

<类型>(<范围>): <描述>

范围可省略，如：fix: 修复全局样式问题

提交类型说明

| 类型 | 说明 | | -------- | --------------- | | feat | 新增功能 | | update | 更新现有功能 | | fix | 修复bug | | docs | 文档修改 | | style | 代码格式修改 | | refactor | 代码重构 | | test | 测试相关 | | chore | 构建/工具配置等 | | perf | 性能优化 | | revert | 回滚提交 | | ci | CI/CD配置修改 |

git提交示例

feat(auth): 新增用户登录功能

fix(api): 修复获取用户信息接口错误

docs(readme): 更新项目说明文档

13. 技术支持

如有问题，请参考：

• Vue 3 文档
• TypeScript 文档
• Vite 文档
• Ant Design Vue 文档
• Pinia 文档