创建项目
本指南详细介绍如何使用 Flu CLI VSCode 扩展创建 Flutter 项目。
创建方式
扩展提供 2 种创建项目的方式，选择你喜欢的即可。
方式 1：右键菜单（推荐）⭐
这是最直观、最快速的方式：
- 在 VSCode 资源管理器中，右键点击任意文件夹
- 选择
Flu: 新建项目（或Flu: New Project） - 按照向导完成创建
优点：
- 所见即所得，直接在目标位置创建
- 无需手动选择目录
- 操作直观
方式 2：命令面板
- 打开命令面板
- macOS:
Cmd+Shift+P - Windows/Linux:
Ctrl+Shift+P
- macOS:
- 输入
Flu: New Project - 选择要创建项目的目录
- 按照向导完成创建
优点：
- 可以快速访问（通过快捷键）
- 适合键盘流用户
创建流程
无论使用哪种方式，创建流程都是一样的：
步骤 1：选择模板
扩展会显示可用的模板列表：
内置模板
| 模板 | 说明 | 项目规模 | 团队规模 |
|---|---|---|---|
| Flutter Native | 纯净的 flutter create 项目 | 任意 | 任意 |
| Lite | 轻量级 MVVM 结构 | 小型（<10k 行） | 1-3 人 |
| Modular | 基于 Feature 的模块化架构 | 中大型（10k-50k 行） | 3-10 人 |
| Clean | 整洁架构（Clean Architecture） | 大型（>20k 行） | 5+ 人 |
自定义模板
如果你添加了自定义模板，它们也会显示在列表中。
选择建议：
- 🆕 首次使用：选择 Modular，它提供了良好的项目结构
- 🚀 快速原型：选择 Lite，结构简单，上手快
- 🏢 企业项目：选择 Clean，架构清晰，易于维护
- 🎯 团队规范：使用自定义模板，统一团队标准
步骤 2：输入项目名称
输入项目名称，如 my_app。
命名规则：
- 只能包含小写字母、数字和下划线
- 必须以字母开头
- 不能使用 Dart 关键字（如
class、if等） - 推荐使用下划线分隔（如
my_flutter_app）
示例：
- ✅
my_app - ✅
todo_list - ✅
user_management_system - ❌
MyApp（不能有大写字母） - ❌
my-app（不能使用连字符） - ❌
123app（不能以数字开头）
步骤 3：输入包名
输入 Android/iOS 包名，如 com.example.my_app。
命名规则：
- 使用反向域名格式
- 只能包含小写字母、数字和点号
- 至少包含两个部分（用点号分隔）
示例：
- ✅
com.example.my_app - ✅
com.mycompany.todolist - ✅
io.github.username.app - ❌
myapp（缺少域名部分） - ❌
com.Example.MyApp（不能有大写字母）
默认值：com.example.项目名
步骤 4：确认创建
扩展会显示项目信息摘要：
项目名称: my_app
模板: Modular
包名: com.example.my_app
创建路径: /Users/username/projects/my_app确认无误后，点击 "创建" 开始创建项目。
步骤 5：等待完成
扩展会执行以下操作：
- ✅ 检查目标目录
- ✅ 下载/复制模板
- ✅ 替换项目名称和包名
- ✅ 初始化 Git 仓库（如果需要）
- ✅ 运行
flutter pub get - ✅ 打开项目
进度提示：
- 扩展会在右下角显示进度通知
- 可以在输出面板查看详细日志
步骤 6：项目创建完成
项目创建完成后：
- 项目会在新窗口中自动打开
- 依赖已自动安装
- 可以直接运行
flutter run
模板详解
Flutter Native
特点：
- 纯净的
flutter create项目 - 无任何架构约束
- 适合学习或简单项目
项目结构：
my_app/
├── lib/
│ └── main.dart
├── test/
├── pubspec.yaml
└── README.md适用场景：
- Flutter 初学者
- 简单的演示项目
- 不需要复杂架构的小工具
Lite
特点：
- 轻量级 MVVM 架构
- 简单的目录结构
- 快速上手
项目结构：
my_app/
├── lib/
│ ├── main.dart
│ ├── pages/ # 页面
│ ├── viewmodels/ # 视图模型
│ ├── widgets/ # 通用组件
│ ├── models/ # 数据模型
│ ├── services/ # 服务层
│ └── utils/ # 工具类
├── pubspec.yaml
└── README.md适用场景：
- 快速原型开发
- 小型项目（<10k 行代码）
- 1-3 人团队
- 学习 MVVM 架构
优点：
- 结构简单，易于理解
- 上手快，学习成本低
- 适合快速迭代
缺点：
- 不适合大型项目
- 缺少模块化支持
Modular（推荐）
特点：
- 基于 Feature 的模块化架构
- 清晰的分层结构
- 适合团队协作
项目结构：
my_app/
├── lib/
│ ├── main.dart
│ ├── core/ # 核心基础设施
│ │ ├── theme/ # 主题系统
│ │ ├── router/ # 路由系统
│ │ ├── constants/ # 常量定义
│ │ └── base/ # 基础类
│ ├── shared/ # 共享资源
│ │ ├── widgets/ # 通用组件
│ │ ├── utils/ # 工具类
│ │ └── services/ # 通用服务
│ └── features/ # 业务功能模块
│ ├── home/ # 首页模块
│ │ ├── pages/
│ │ ├── viewmodels/
│ │ ├── widgets/
│ │ ├── services/
│ │ ├── models/
│ │ └── index.dart
│ └── user/ # 用户模块
│ └── ...
├── pubspec.yaml
└── README.md适用场景：
- 中大型项目（10k-50k 行代码）
- 3-10 人团队
- 需要模块化开发
- 长期维护的项目
优点：
- 模块化，易于扩展
- 职责清晰，便于协作
- 适合大多数商业项目
缺点：
- 初期结构较复杂
- 需要一定学习成本
Clean Architecture
特点：
- 整洁架构（Clean Architecture）
- 严格的分层和依赖规则
- 高度可测试
项目结构：
my_app/
├── lib/
│ ├── main.dart
│ ├── core/ # 核心层
│ │ ├── error/ # 错误处理
│ │ ├── usecases/ # 用例基类
│ │ └── utils/ # 工具类
│ ├── features/ # 功能模块
│ │ └── user/
│ │ ├── domain/ # 领域层
│ │ │ ├── entities/ # 实体
│ │ │ ├── repositories/ # 仓储接口
│ │ │ └── usecases/ # 用例
│ │ ├── data/ # 数据层
│ │ │ ├── models/ # 数据模型
│ │ │ ├── datasources/ # 数据源
│ │ │ └── repositories/ # 仓储实现
│ │ └── presentation/ # 表现层
│ │ ├── pages/
│ │ ├── viewmodels/
│ │ └── widgets/
│ └── injection.dart # 依赖注入
├── pubspec.yaml
└── README.md适用场景：
- 大型项目（>20k 行代码）
- 5+ 人团队
- 企业级应用
- 需要高度可测试性
优点：
- 架构清晰，易于测试
- 依赖规则严格，易于维护
- 适合长期大型项目
缺点：
- 结构复杂，学习成本高
- 初期开发速度较慢
- 可能过度设计
冲突处理
如果目标目录已存在同名项目，扩展会提示你选择：
选项 1：覆盖
删除现有目录并重新创建。
警告：此操作不可恢复，请确保已备份重要数据！
选项 2：取消
取消创建操作，保留现有目录。
选项 3：重命名
输入新的项目名称，避免冲突。
创建后操作
项目创建完成后，建议执行以下操作：
1. 检查依赖
bash
flutter pub get2. 运行项目
bash
flutter run3. 运行测试
bash
flutter test4. 检查代码
bash
flutter analyze5. 格式化代码
bash
flutter format .自定义模板
除了内置模板，你还可以使用自定义模板。
添加 Git 模板
- 创建项目时选择 "自定义模板..."
- 选择 "添加自定义模板"
- 选择 "Git 仓库"
- 输入 Git URL（如
https://gitee.com/my-team/flutter-template.git） - 输入模板名称（如
团队标准模板） - 等待下载完成
添加本地模板
- 创建项目时选择 "自定义模板..."
- 选择 "添加自定义模板"
- 选择 "本地文件夹"
- 浏览到模板目录
- 输入模板名称
- 完成
使用自定义模板
添加后，自定义模板会出现在模板列表中，使用方式与内置模板相同。
详细说明请查看 自定义模板。
常见问题
创建失败怎么办？
可能原因：
- Flutter SDK 未安装或未在 PATH 中
- 目标目录没有写入权限
- 网络问题（下载模板失败）
- 磁盘空间不足
解决方案：
- 检查 Flutter 安装：
flutter doctor - 检查目录权限
- 检查网络连接
- 查看输出面板的错误信息
创建速度慢？
可能原因：
- 网络速度慢（下载依赖）
- 磁盘 I/O 慢
- 首次创建（需要下载模板）
解决方案：
- 使用国内镜像：bash
export PUB_HOSTED_URL=https://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn - 使用 SSD 硬盘
- 等待首次下载完成（后续会使用缓存）
如何修改已创建的项目？
创建后的项目是标准的 Flutter 项目，可以自由修改：
- 修改
pubspec.yaml添加依赖 - 修改
lib/main.dart自定义入口 - 添加新的功能模块
- 调整项目结构
可以在现有目录中创建吗？
可以，但建议在空目录中创建。如果目录不为空：
- 扩展会提示是否覆盖
- 选择覆盖会删除现有内容
- 选择取消会保留现有内容
下一步
项目创建完成后，你可以：