VSCode 插件上手指南

欢迎使用 Flu CLI VSCode 扩展！本指南将帮助你在 5 分钟内上手，创建你的第一个 Flutter 项目。

环境要求

在开始之前，请确保你的开发环境满足以下要求：

VSCode: >= 1.80.0
Flutter: >= 3.0.0（推荐）
Dart: >= 3.0.0（推荐）

检查版本：

bash

flutter --version # 3.0.0 或更高
dart --version    # 3.0.0 或更高

安装扩展

方式 1：VSCode 市场安装（推荐）

打开 VSCode
点击左侧扩展图标（或按 Cmd+Shift+X / Ctrl+Shift+X）
搜索 "Flu CLI"
点击安装

方式 2：命令面板安装

按 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows/Linux)
输入 Extensions: Install Extensions
搜索 "Flu CLI"
点击安装

验证安装

安装完成后，在命令面板中输入 Flu，你应该能看到以下命令：

Flu: New Project
Flu: Generate
Flu: Init
Flu: Publish Center

创建第一个项目

方式 1：右键菜单（推荐）⭐

这是最直观、最快速的方式：

在 VSCode 资源管理器中，右键点击任意文件夹
选择 Flu: 新建项目（或 Flu: New Project）
按照向导完成创建

方式 2：命令面板

打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）
输入 Flu: New Project
选择要创建项目的目录
按照向导完成创建

项目模板选择

扩展提供 4 种内置模板：

模板	说明	适用场景
Flutter Native	纯净的 `flutter create` 项目	不需要架构约束
Lite	轻量级 MVVM 结构	小型项目、快速原型
Modular	基于 Feature 的模块化架构	中大型项目（推荐）
Clean	整洁架构（Clean Architecture）	企业级应用

首次使用推荐：选择 Modular 模板，它提供了良好的项目结构，适合大多数场景。

智能网络层

在创建项目时，扩展会询问是否包含网络层。

✅ 包含网络层 (推荐)：自动集成 Dio、拦截器、Mock 支持和 API 示例。
❌ 不包含：纯净项目，适合离线应用。

建议勾选包含，以获得开箱即用的网络开发体验。

生成第一个文件

项目创建完成后，让我们添加一个新页面。 重要说明：Flu CLI 的右键生成功能非常智能，你可以在项目中的任意位置点击右键，扩展会根据：

你选择的文件类型（Page / ViewModel / Widget 等）
.flu-cli.json 中配置的路径规则

自动将文件创建到正确的目录下。无需手动定位到目标文件夹。

步骤 1：使用右键菜单生成

操作步骤：

在资源管理器中，右键点击项目中的任意文件夹（例如项目根目录、lib 文件夹等）
选择 Flu: 生成文件（或 Flu: Generate）

步骤 2：选择类型

在弹出的选择框中，选择 Page

步骤 3：输入名称

输入页面名称，如 profile（不需要加 _page 后缀，扩展会自动添加）

步骤 4：选择页面类型

选择页面类型：

Stateful Widget：有状态组件（推荐）
Stateless Widget：无状态组件

完成！

扩展会自动生成以下文件：

lib/features/home/pages/
└── profile_page.dart

lib/features/home/viewmodels/
└── profile_viewmodel.dart

并且会自动更新 index.dart 导出文件。

运行项目

打开终端（Ctrl+`）
运行以下命令：

bash

# 安装依赖
flutter pub get

# 运行项目
flutter run

完整示例：创建用户模块

让我们创建一个完整的用户管理功能：

1. 创建模块

右键点击文件夹
选择 Flu: 生成文件
选择 Module
输入名称：user

生成结构：

lib/features/user/
├── pages/
├── viewmodels/
├── widgets/
├── services/
├── models/
└── index.dart

2. 添加用户列表页面

右键点击文件夹
选择 Flu: 生成文件
选择 Page
输入名称：user_list
选择 Stateful Widget

3. 添加用户详情页面

右键点击文件夹
选择 Flu: 生成文件
选择 Page
输入名称：user_detail

4. 添加用户模型

右键点击文件夹
选择 Flu: 生成文件
选择 Model
输入名称：user

5. 添加用户服务

右键点击文件夹
选择 Flu: 生成文件
选择 Service
输入名称：user

6. 添加自定义组件

右键点击文件夹
选择 Flu: 生成文件
选择 Widget
输入名称：user_card

完成！你已经创建了一个完整的用户管理模块。

在现有项目中使用

如果你已经有一个 Flutter 项目，也可以使用 Flu CLI 扩展：

步骤 1：初始化配置

在项目根目录右键
选择 Flu: 初始化项目（或 Flu: Init）
扩展会自动生成 .flu-cli.json 配置文件

步骤 2：自定义配置

编辑生成的 .flu-cli.json，匹配你的项目结构：

json

{
  "generators": {
    "page": {
      "path": "lib/pages", // 你的页面路径
      "defaultType": "stateful", // 默认类型
      "withViewModel": true // 是否生成 ViewModel
    }
  }
}

步骤 3：开始使用

现在你可以在项目中使用 Flu: 生成文件 命令了！

详细配置说明请查看配置详解。

使用智能代码片段

Flu CLI 提供智能动态代码片段功能，会根据你的项目配置（.flu-cli.json）自动适配可用的代码片段。

✨ 核心特性

🎯 智能适配：根据项目架构自动显示/隐藏相关代码片段
🔄 动态过滤：如果项目禁用了 BasePage，相关片段会自动隐藏
⚡ 零配置：打开 .dart 文件即可使用，无需额外设置

快速使用

在 .dart 文件中输入以下前缀，然后按 Tab：

前缀	说明	显示条件
`stPage`	Stateful Page (BasePage)	启用 BasePage
`stSimplePage`	Stateful Page (原生)	始终显示
`lessPage`	Stateless Page	始终显示
`viewmodel`	ViewModel 类	启用 BasePage
`stWidget`	StatefulWidget	始终显示
`lessWidget`	StatelessWidget	始终显示
`model`	数据模型类	始终显示
`service`	服务类	始终显示

示例：智能适配

项目配置 (启用 BasePage):

json

{
  "template": "lite",
  "generators": {
    "page": {
      "withBasePage": true // 启用 BasePage
    }
  }
}

输入 stPage 然后按 Tab，生成 BasePage 架构代码：

dart

import 'package:flutter/material.dart';
import '../base/base_page.dart';
import '../viewmodels/home_viewmodel.dart';

class HomePage extends BasePage<HomeViewModel> {
  const HomePage({Key? key}) : super(key: key);

  @override
  HomeViewModel createViewModel() => HomeViewModel();

  @override
  Widget buildPage(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Container(),
    );
  }
}

如果禁用 BasePage（withBasePage: false），stPage 和 viewmodel 片段会自动隐藏，改用 stSimplePage 生成标准 StatefulWidget。

💡 提示：查看完整片段列表和详细说明了解所有可用代码片段。

下一步

恭喜！你已经掌握了 Flu CLI VSCode 扩展的基本使用。接下来你可以：

📖 查看创建项目详解了解更多创建选项
🎯 学习生成文件详解掌握所有生成类型
🚀 使用发布中心一键构建 + 多平台上传
🔧 探索配置详解自定义生成规则
🎨 使用自定义模板打造团队规范
💡 查看最佳实践学习推荐用法

常见问题

找不到 Flu 命令？

确保扩展已正确安装并启用。在扩展面板中搜索 "Flu CLI"，检查是否显示 "已启用"。

右键菜单没有 Flu 选项？

右键菜单只在文件夹上显示。确保你右键点击的是文件夹，而不是文件。

生成的文件路径不对？

检查项目根目录是否有 .flu-cli.json 配置文件。如果没有，运行 Flu: Init 初始化配置。

如何查看扩展日志？

按 Cmd+Shift+P / Ctrl+Shift+P
输入 Developer: Show Logs
选择 Extension Host

更多问题请查看故障排除和常见问题。

获取帮助

如果遇到问题，可以：

查看故障排除
查看常见问题
提交 Gitee Issue
加入社区讨论

命令行用户？

如果你更习惯使用终端，可以试试 Flu CLI 命令行工具：

bash

# 安装
npm install -g @flu-cli/cli

# 创建项目
flu-cli create my-app

# 生成文件
flu-cli generate page home

👉 查看 CLI 完整文档

VSCode 插件上手指南 ​

环境要求 ​

安装扩展 ​

方式 1：VSCode 市场安装（推荐） ​

方式 2：命令面板安装 ​

验证安装 ​

创建第一个项目 ​

方式 1：右键菜单（推荐）⭐ ​

方式 2：命令面板 ​

项目模板选择 ​

智能网络层 ​

生成第一个文件 ​

步骤 1：使用右键菜单生成 ​

步骤 2：选择类型 ​

步骤 3：输入名称 ​

步骤 4：选择页面类型 ​

完成！ ​

运行项目 ​

完整示例：创建用户模块 ​

1. 创建模块 ​

2. 添加用户列表页面 ​

3. 添加用户详情页面 ​

4. 添加用户模型 ​

5. 添加用户服务 ​

6. 添加自定义组件 ​

在现有项目中使用 ​

步骤 1：初始化配置 ​

步骤 2：自定义配置 ​

步骤 3：开始使用 ​

使用智能代码片段 ​

✨ 核心特性 ​

快速使用 ​

示例：智能适配 ​

下一步 ​

常见问题 ​

找不到 Flu 命令？ ​

右键菜单没有 Flu 选项？ ​

生成的文件路径不对？ ​

如何查看扩展日志？ ​

获取帮助 ​

命令行用户？ ​

VSCode 插件上手指南

环境要求

安装扩展

方式 1：VSCode 市场安装（推荐）

方式 2：命令面板安装

验证安装

创建第一个项目

方式 1：右键菜单（推荐）⭐

方式 2：命令面板

项目模板选择

智能网络层

生成第一个文件

步骤 1：使用右键菜单生成

步骤 2：选择类型

步骤 3：输入名称

步骤 4：选择页面类型

完成！

运行项目

完整示例：创建用户模块

1. 创建模块

2. 添加用户列表页面

3. 添加用户详情页面

4. 添加用户模型

5. 添加用户服务

6. 添加自定义组件

在现有项目中使用

步骤 1：初始化配置

步骤 2：自定义配置

步骤 3：开始使用

使用智能代码片段

✨ 核心特性

快速使用

示例：智能适配

下一步

常见问题

找不到 Flu 命令？

右键菜单没有 Flu 选项？

生成的文件路径不对？

如何查看扩展日志？

获取帮助

命令行用户？