附录B：常见问题
环境配置问题
flutter 命令找不到
- 确认
flutter/bin已加入PATH - 执行
source ~/.bashrc或重新打开终端 - 检查路径是否包含中文或空格
Gradle 下载依赖失败（403 错误）
确保已配置 ~/.gradle/init.gradle 文件，使用国内镜像。详见 环境安装 章节。
鸿蒙设备无法识别
- 确认
HDC_HOME环境变量已正确配置 - 确认设备已开启开发者模式和 USB 调试
- 运行
hdc list targets检查设备是否连接
flutter doctor 提示 OpenHarmony toolchain 不可用
- 确认
DEVECO_SDK_HOME指向正确的 SDK 目录 - 确认已运行
flutter config --ohos-sdk $DEVECO_SDK_HOME - 确认已运行
flutter precache --ohos
DevEco Studio 打开 ohos 目录报错 flutter-hvigor-plugin 找不到
在 Windows 上克隆 flutter-ohos 的 Git 仓库后，用 DevEco Studio 打开 ohos 目录时，可能会遇到以下报错：
hvigor ERROR: Error Cannot find module 'flutter-hvigor-plugin'
Require stack:
- D:\code-demo\flutter\demo\riverpod\ohos\hvigorconfig.ts原因：hvigor 查找模块的位置是它自己的缓存工作区 ~/.hvigor/project_caches/<hash>/workspace/node_modules/，而非项目目录下的 node_modules。由于 hvigor-config.json5 的 dependencies 为空，hvigor 不会在缓存工作区安装 flutter-hvigor-plugin，导致找不到模块。
解决方法：在 ohos/hvigor/hvigor-config.json5 的 dependencies 中添加 flutter-hvigor-plugin，指向 Flutter SDK 中的插件路径：
{
"modelVersion": "5.1.0",
"dependencies": {
"flutter-hvigor-plugin": "file:<Flutter SDK路径>/packages/flutter_tools/hvigor"
}
}例如：
{
"modelVersion": "5.1.0",
"dependencies": {
"flutter-hvigor-plugin": "file:D:\\code-demo\\flutter\\version\\FlutterOH\\3.35.8-ohos-0.0.3\\packages\\flutter_tools\\hvigor"
}
}请将
<Flutter SDK路径>替换为你实际的 Flutter 鸿蒙版 SDK 路径，可通过flutter --version确认。修改后重新用 DevEco Studio 打开项目即可。
两个 Flutter 版本冲突
两种方案使用不同的 SDK 目录，只要 PATH 中只包含一个版本的路径，就不会冲突。使用切换脚本来管理。
路径问题
路径中包含中文或空格
Flutter SDK、项目目录、Android SDK 的路径中不能包含中文或空格，否则会导致各种奇怪的错误。
# ❌ 错误示例
C:\我的开发\flutter
C:\Program Files\flutter
/Users/用户名/我的项目/
# ✅ 正确示例
C:\src\flutter
C:\Users\username\projects\my_app长路径问题（Windows）
Windows 有 260 字符路径长度限制。如果项目路径太深，可能导致构建失败。建议将项目放在浅层目录。
开发问题
热重载不生效
- 修改了
pubspec.yaml后需要重新flutter pub get - 修改了
main()函数需要热重启（按R），热重载（按r）不够 - 修改了全局变量或静态变量需要热重启
RenderFlex 溢出
最常见的新手错误，Column/Row 中内容超出可用空间：
// ❌ 溢出
Column(
children: [
VeryTallWidget(), // 太高了，超出屏幕
],
)
// ✅ 解决：用 Expanded 或 SingleChildScrollView
Column(
children: [
Expanded(child: VeryTallWidget()), // 限制在剩余空间
],
)
// 或者
SingleChildScrollView(
child: Column(
children: [VeryTallWidget()],
),
)setState 后 UI 没更新
- 检查是否忘记了
notifyListeners()（使用 Provider 时） - 检查是否在异步操作后没有检查
mounted - 检查
ref.watch/ref.read是否用对了（Riverpod 场景）
网络请求失败
- 检查网络权限是否已声明
- Android 9+ 默认不允许 HTTP 请求，需在
AndroidManifest.xml中配置android:usesCleartextTraffic="true"或使用 HTTPS - iOS 需在
Info.plist中配置NSAppTransportSecurity - 检查国内镜像是否配置正确
图片不显示
- 检查
pubspec.yaml中是否声明了assets - 检查图片路径是否正确（区分大小写）
- 网络图片检查 URL 和网络权限
iOS 构建失败
- 确认在 macOS 上操作
- 确认 Xcode 和 CocoaPods 已安装
- 运行
cd ios && pod install && cd ..
包管理问题
pub get 失败
- 检查
PUB_HOSTED_URL和FLUTTER_STORAGE_BASE_URL是否配置 - 执行
source ~/.bashrc使环境变量生效 - 删除
pubspec.lock后重试 - 清理缓存：
flutter pub cache clean
包版本冲突
# 查看依赖树
flutter pub deps
# 查看过期依赖
flutter pub outdated
# 升级依赖
flutter pub upgrade
# 强制获取
flutter pub get --no-example构建问题
Android 构建失败
- 检查
android/app/build.gradle中的 SDK 版本配置 - 检查签名配置是否正确
- 运行
flutter clean后重新构建 - 检查
android/目录下的build.gradle是否配置了镜像
iOS 构建失败
- 在
ios/目录运行pod install - 清理 Xcode 缓存：Xcode → Window → Organizer → Projects → Delete Derived Data
- 检查签名和 Provisioning Profile
构建包体积过大
- 使用
--split-debug-info分离调试信息 - 使用
--obfuscate代码混淆 - 使用
--tree-shake-icons移除未使用的图标 - 检查是否引入了过大的资源文件
flutter build apk --split-debug-info=/<project-name>/debug_info --obfuscate调试技巧
查看日志
# 实时查看日志
flutter logs
# 在代码中打印
debugPrint('调试信息'); // 比 print 更安全检查 Widget 树
在 DevTools 中使用 Flutter Inspector 可视化查看 Widget 树和渲染信息。
性能分析
// 在 MaterialApp 中开启
showPerformanceOverlay: true,
debugShowCheckedModeBanner: false,