本章整理了 Flutter 开发中常见的问题及解决方案。
9.1 环境相关问题
问题：flutter 命令找不到
症状：
flutter: command not found解决：
- 检查 Flutter 是否正确安装
- 检查 PATH 环境变量是否包含 flutter/bin
- 重新打开终端使环境变量生效
1# 检查 flutter 位置
2which flutter
3
4# 检查 PATH
5echo $PATH
6
7# 临时添加 PATH（仅当前终端）
8export PATH="$PATH:/path/to/flutter/bin"问题：flutter doctor 显示 Android SDK 未配置
症状：
[!] Android toolchain - develop for Android devices
✗ Unable to locate Android SDK.解决：
- 打开 Android Studio
- 打开 SDK Manager（Tools > SDK Manager）
- 安装 Android SDK
- 设置环境变量：
1# Linux/Mac
2export ANDROID_SDK_ROOT=$HOME/Android/Sdk
3
4# Windows（系统属性 > 环境变量）
5set ANDROID_SDK_ROOT=C:\Users\YourName\AppData\Local\Android\Sdk问题：模拟器无法启动
症状：
Failed to launch emulator: No emulator found解决：
- 确保已创建模拟器
- 检查虚拟化是否启用（BIOS 设置）
- 安装 Intel HAXM（Windows）或启用 Hyper-V
- 尝试使用真机调试
9.2 依赖相关问题
问题：pub get 失败
症状：
Could not resolve all dependencies解决：
- 检查网络连接
- 配置国内镜像源：
1export PUB_HOSTED_URL=https://pub.flutter-io.cn
2export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn- 清除缓存重试：
1flutter clean
2flutter pub get问题：版本冲突
症状：
Because todo_app depends on provider ^5.0.0 which doesn't support null safety解决：
- 升级依赖版本
- 使用兼容版本：
1dependencies:
2 provider: ^6.1.1 # 使用最新版本- 运行
flutter pub upgrade
9.3 代码相关问题
问题：Null check operator used on a null value
症状：
Null check operator used on a null value解决：
检查使用了 ! 运算符的地方，确保值不为 null：
// ❌ 可能报错
final value = someNullableValue!;
// ✅ 安全处理
if (someNullableValue != null) {
final value = someNullableValue;
}
// 或
final value = someNullableValue ?? defaultValue;问题：setState() called after dispose()
症状：
setState() called after dispose()解决：
在调用 setState 前检查组件是否已销毁：
if (mounted) {
setState(() {
// 更新状态
});
}问题：Provider 找不到
症状：
Error: Could not find the correct Provider above this Widget解决：
- 确保 Provider 在 Widget 树的上方：
// ✅ 正确：Provider 在 MaterialApp 外层
ChangeNotifierProvider(
create: (_) => TaskProvider(),
child: MaterialApp(...),
)
// ❌ 错误：Provider 在某个页面内
MaterialApp(
home: ChangeNotifierProvider(...), // 其他页面访问不到
)- 确保类型一致：
// 提供的是 TaskProvider
ChangeNotifierProvider(...)
// 获取时也要用 TaskProvider
context.watch()问题：ListView 底部被遮挡
症状：
ListView 滚动到底部时，内容被 FloatingActionButton 遮挡。
解决：
添加底部内边距：
ListView.builder(
padding: const EdgeInsets.only(bottom: 80), // 留出 FAB 空间
itemCount: tasks.length,
itemBuilder: ...,
)9.4 构建相关问题
问题：构建失败，提示 Gradle 错误
症状：
FAILURE: Build failed with an exception解决：
- 清理构建缓存：
1cd android
2./gradlew clean
3cd ..
4flutter clean
5flutter pub get- 检查 Gradle 版本兼容性
- 更新 Android Gradle Plugin
问题：iOS 构建失败
症状：
error: Signing for "Runner" requires a development team解决：
- 打开 ios/Runner.xcworkspace
- 在 Xcode 中配置 Signing & Capabilities
- 选择你的开发团队
9.5 运行时问题
问题：应用白屏/黑屏
可能原因：
- main.dart 中有错误
- 初始化失败
解决：
- 检查控制台输出
- 添加错误捕获：
void main() {
FlutterError.onError = (FlutterErrorDetails details) {
print('Flutter Error: ${details.exception}');
};
runApp(MyApp());
}问题：热重载不工作
症状：
修改代码后，热重载没有反应。
解决：
- 确保在终端中按了
r键 - 某些更改需要热重启（按
R） - 检查是否有语法错误
问题：SharedPreferences 数据丢失
症状：
应用重启后，保存的数据不见了。
可能原因：
- 使用了模拟器，数据在重启后清除
- 存储时发生错误
解决：
- 检查存储是否成功：
try {
await StorageService.saveTasks(tasks);
print('保存成功');
} catch (e) {
print('保存失败: $e');
}- 使用真机测试
9.6 调试技巧
打印日志
// 简单打印
print('调试信息');
// 打印对象
print('任务: ${task.toString()}');
// 格式化输出
print('任务数: ${tasks.length}, 筛选: $currentFilter');使用调试器
在 VS Code 或 Android Studio 中：
- 设置断点（点击行号左侧）
- 按 F5 启动调试
- 使用以下快捷键：
- F5 - 继续
- F10 - 单步跳过
- F11 - 单步进入
- Shift+F11 - 单步跳出
Widget 检查
在应用运行时：
- 点击右上角的调试标志
- 选择 "Select Widget Mode"
- 点击界面上的组件查看其属性
性能分析
1# 启动性能分析模式
2flutter run --profile
3
4# 查看性能图层
5# 在真机上摇晃设备，选择 "Performance Overlay"9.7 获取帮助
如果遇到问题无法解决：
- 查看官方文档
- 搜索 Stack Overflow
- 查看 GitHub Issues
- 使用 Flutter 社区资源
- Flutter 中文社区：https://flutter.cn/
- Flutter 中文文档：https://flutter.cn/docs
- 查看错误信息
- 仔细阅读错误堆栈
- 搜索错误信息中的关键词
下一步：第十章：扩展功能建议