aisee/技术文档/Flutter开发环境搭建.md

# AISee Flutter 开发环境搭建指南

## 系统要求

- **操作系统**：Windows 10/11（64位）
- **内存**：至少 8GB RAM（推荐 16GB）
- **硬盘**：至少 10GB 可用空间
- **处理器**：Intel/AMD 处理器

## 一、安装 Flutter SDK

### 1. 下载 Flutter SDK
```bash
# 官网下载（可能较慢）
https://flutter.dev/docs/get-started/install/windows

# 推荐：使用国内镜像
https://flutter.cn/docs/get-started/install/windows

# 下载稳定版
flutter_windows_3.16.9-stable.zip
```

### 2. 解压 Flutter SDK
```bash
# 解压到：
C:\src\flutter

# 注意：不要放在需要管理员权限的目录（如 Program Files）
```

### 3. 配置环境变量
```bash
# 1. 右键"此电脑" -> 属性 -> 高级系统设置 -> 环境变量

# 2. 在"用户变量"中新建：
变量名：FLUTTER_HOME
变量值：C:\src\flutter

# 3. 编辑 Path 变量，添加：
%FLUTTER_HOME%\bin
C:\src\flutter\bin\cache\dart-sdk\bin

# 4. 配置国内镜像（重要！）
变量名：PUB_HOSTED_URL
变量值：https://pub.flutter-io.cn

变量名：FLUTTER_STORAGE_BASE_URL
变量值：https://storage.flutter-io.cn

# 5. 验证
flutter --version
dart --version
```

### 4. 运行 Flutter Doctor
```bash
# 检查环境
flutter doctor

# 输出示例：
Doctor summary (to see all details, run flutter doctor -v):
[√] Flutter (Channel stable, 3.16.9, on Microsoft Windows)
[!] Android toolchain - develop for Android devices
[!] Chrome - develop for the web
[!] Visual Studio - develop for Windows
[!] Android Studio (not installed)
[√] VS Code (version 1.85.0)
[√] Connected device (1 available)
```

## 二、安装 Android 开发环境

### 1. 安装 Android Studio
```bash
# 下载地址
https://developer.android.com/studio

# 安装步骤（参考之前的 Android 环境文档）
1. 安装 Android Studio
2. 安装 Android SDK (API 26-34)
3. 配置 ANDROID_HOME 环境变量
```

### 2. 安装 Android SDK 命令行工具
```bash
# 在 Android Studio 中
# Tools -> SDK Manager -> SDK Tools

勾选：
☑ Android SDK Command-line Tools
☑ Android SDK Build-Tools
☑ Android SDK Platform-Tools
☑ Android Emulator
```

### 3. 接受 Android 许可
```bash
flutter doctor --android-licenses

# 输入 y 接受所有许可
```

## 三、安装 Visual Studio Code

### 1. 下载安装 VS Code
```bash
# 官网
https://code.visualstudio.com/

# 下载 Windows 64-bit 版本
VSCodeUserSetup-x64-1.85.0.exe
```

### 2. 安装 Flutter 插件
```bash
# 打开 VS Code
# 按 Ctrl+Shift+X 打开扩展面板

搜索并安装：
1. Flutter（自动安装 Dart 插件）
2. Dart
3. Flutter Widget Snippets（可选）
4. Awesome Flutter Snippets（可选）
5. Pubspec Assist（可选）
```

### 3. 配置 VS Code
```bash
# 按 Ctrl+Shift+P 打开命令面板
# 输入：Flutter: New Project

# 如果能看到选项，说明配置成功
```

## 四、创建和运行测试项目

### 1. 创建测试项目
```bash
# 打开命令行
cd C:\Users\xdedmi\Desktop\aisee

# 创建 Flutter 项目
flutter create hello_flutter

# 进入项目目录
cd hello_flutter

# 查看项目结构
dir
```

### 2. 启动 Android 模拟器
```bash
# 查看可用设备
flutter devices

# 如果没有设备，创建模拟器
# 打开 Android Studio -> Device Manager -> Create Device

# 或使用命令行创建
flutter emulators
flutter emulators --launch <emulator_id>
```

### 3. 运行项目
```bash
# 确保模拟器已启动
flutter devices

# 运行项目
flutter run

# 或在 VS Code 中按 F5
```

### 4. 热重载测试
```bash
# 修改 lib/main.dart 中的文本
# 保存文件（Ctrl+S）
# 应该看到模拟器自动更新

# 或在终端按：
r - 热重载
R - 热重启
q - 退出
```

## 五、安装必要的工具

### 1. Git（如果还没安装）
```bash
# 下载
https://git-scm.com/download/win

# 安装并配置
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
```

### 2. Chrome（用于 Web 调试）
```bash
# Flutter 支持 Web 开发
# 安装 Chrome 浏览器用于调试

# 启用 Web 支持
flutter config --enable-web

# 运行 Web 版本
flutter run -d chrome
```

## 六、Flutter 常用命令

### 项目管理
```bash
# 创建新项目
flutter create project_name

# 创建指定平台项目
flutter create --platforms=android,ios project_name

# 获取依赖
flutter pub get

# 更新依赖
flutter pub upgrade

# 清理项目
flutter clean
```

### 运行和调试
```bash
# 运行项目
flutter run

# 指定设备运行
flutter run -d <device_id>

# Release 模式运行
flutter run --release

# 查看日志
flutter logs
```

### 构建
```bash
# 构建 APK
flutter build apk

# 构建 App Bundle
flutter build appbundle

# 构建 iOS（需要 macOS）
flutter build ios
```

### 分析和测试
```bash
# 分析代码
flutter analyze

# 运行测试
flutter test

# 查看设备
flutter devices

# 检查环境
flutter doctor -v
```

## 七、配置国内镜像加速

### 永久配置（推荐）
```bash
# 在环境变量中添加：
PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
```

### 临时配置
```bash
# Windows PowerShell
$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

# CMD
set PUB_HOSTED_URL=https://pub.flutter-io.cn
set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
```

## 八、常见问题解决

### 1. Flutter Doctor 问题

#### Android toolchain 问题
```bash
# 问题：Android license status unknown
# 解决：
flutter doctor --android-licenses

# 问题：cmdline-tools component is missing
# 解决：在 Android Studio SDK Manager 中安装 Command-line Tools
```

#### Visual Studio 问题（Windows 桌面开发）
```bash
# 如果需要开发 Windows 桌面应用
# 下载安装 Visual Studio 2022 Community
# 选择"使用 C++ 的桌面开发"工作负载
```

### 2. 网络问题
```bash
# 问题：下载依赖超时
# 解决：
1. 配置国内镜像（见上文）
2. 使用代理
3. 手动下载依赖包
```

### 3. 模拟器问题
```bash
# 问题：模拟器启动失败
# 解决：
1. 检查 BIOS 虚拟化是否开启
2. 关闭 Hyper-V
3. 使用真机调试

# 问题：模拟器很慢
# 解决：
1. 使用 x86_64 镜像
2. 增加模拟器 RAM
3. 使用真机调试
```

### 4. 真机调试
```bash
# Android 真机调试步骤：
1. 手机开启开发者选项
2. 开启 USB 调试
3. 连接手机到电脑
4. 允许 USB 调试授权
5. 运行：flutter devices
6. 运行：flutter run
```

## 九、VS Code 快捷键

### Flutter 开发常用快捷键
```bash
F5              - 启动调试
Shift+F5        - 停止调试
Ctrl+F5         - 运行（不调试）
Ctrl+Shift+F5   - 重启调试

Ctrl+S          - 保存并热重载
Ctrl+Shift+P    - 命令面板
Ctrl+Space      - 代码补全
F12             - 跳转到定义
Alt+F12         - 查看定义
Shift+F12       - 查看引用

Ctrl+/          - 注释/取消注释
Ctrl+Shift+K    - 删除行
Alt+Up/Down     - 移动行
Ctrl+D          - 选择下一个相同内容
```

### Flutter 特定命令
```bash
# Ctrl+Shift+P 打开命令面板，输入：

Flutter: New Project          - 创建新项目
Flutter: Hot Reload          - 热重载
Flutter: Hot Restart         - 热重启
Flutter: Open DevTools       - 打开开发者工具
Flutter: Run Flutter Doctor  - 运行环境检查
Flutter: Clean Project       - 清理项目
```

## 十、开发环境检查清单

```bash
✅ Flutter SDK 安装并配置环境变量
✅ 国内镜像配置完成
✅ Android Studio 安装
✅ Android SDK 安装（API 26-34）
✅ Android 许可接受
✅ VS Code 安装
✅ Flutter 和 Dart 插件安装
✅ Git 安装并配置
✅ 测试项目创建并运行成功
✅ 热重载功能正常
✅ flutter doctor 无严重错误
```

## 十一、验证环境

### 运行完整检查
```bash
# 详细检查
flutter doctor -v

# 期望输出（至少这些项目正常）：
[√] Flutter (Channel stable, 3.16.9)
[√] Android toolchain - develop for Android devices
[√] VS Code (version 1.85.0)
[√] Connected device (1 available)

# 如果有 [!] 或 [×]，根据提示解决
```

### 创建并运行测试项目
```bash
# 1. 创建项目
flutter create test_app
cd test_app

# 2. 启动模拟器或连接真机
flutter devices

# 3. 运行项目
flutter run

# 4. 看到计数器应用说明环境正常
```

## 十二、下一步

环境搭建完成后：
1. ✅ 学习 Dart 语言基础
2. ✅ 学习 Flutter Widget
3. ✅ 创建 AISee 项目
4. ✅ 开始功能开发

---

**预计时间**：
- 下载安装：30-60 分钟
- 配置调试：15-30 分钟
- 总计：1-2 小时

**提示**：
- 首次运行 `flutter doctor` 会下载必要组件，需要时间
- 首次运行项目会下载 Gradle 依赖，需要耐心等待
- 建议使用真机调试，速度更快