Flutter 问题诊断-0.1

安装情况

先决条件：
正常安装flutter & android studio
照着官网教程安装——flutter安装，以及搭配的android stuido下载需要工具：Android SDK Build-Tools、Platform-Tools、SDK包等等
这里只是讨论官网教程没有涉及的意外

flutter doctor 诊断

Android toolchain - develop for Android devices
```
[X] Android toolchain - develop for Android devices
  X ANDROID_HOME = E:\TheAPP\Android\Sdk\sources\android-36
    but Android SDK not found at this location.
```
- SDK包环境变量配置错误，如果是利用Android studio 下载的sdk包，配置路径....../Android/Sdk即可；如果手动下载的，platform文件夹下。完事，再次终端输入flutter doctor 校验
- 👀：值得一提，powershell终端并不能直接刷新系统环境配置；所以显示还是之前错误，需要重启系统；但cmd只要新开一个终端窗口，就能读取到新配的环境配置
Network resources
- 运行flutter run后，显示Running Gradle task 'assembleDebug'.......然后一直卡住，显然gradle镜像无法被访问到；或者某个包无法正常下载
- 运行flutter doctor可以发现
```
[!] Network resources
```
X A network error occurred while checking "https://maven.google.com/": 信号灯超时时间已到
```
无法正常访问到maven.google.com，那就是网络问题（我是有挂梯子的）
- 👀解决办法：
```
  set HTTP_PROXY=http://127.0.0.1:xxxx
  set HTTPS_PROXY=http://127.0.0.1:xxxx
```
  将代理端口设置进flutter中，不太清楚flutter网络怎么走的适配器，涉及到虚拟机一般都有独立适配器
- ❗注意：
  - 上面方法只配置当前终端窗口，如果想自动代理访问，还需要配置环境变量（正常配置即可，变量名就是HTTPS_PROXY 和 HTTP_PROXY）;
  - 没有带梯子，也可修改成国内镜像访问：
```
// 清华大学镜像源
  set PUB_HOSTED_URL=https://pub.flutter-io.cn
  set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
```
    或
```
// 阿里云镜像源
  set PUB_HOSTED_URL=https://mirrors.aliyun.com/dart-pub
  set FLUTTER_STORAGE_BASE_URL=https://mirrors.aliyun.com/flutter
```
    PUB_HOSTED_URL (Dart 包管理器的镜像)
    FLUTTER_STORAGE_BASE_URL (Flutter SDK 存储的镜像)
  - 如果想换种方式，也可以到flutter安装目录下，修改配置文件http_host_validator.dart，路径"....\flutter\packages\flutter_tools\lib\src"；const kMaven变量修改为可访为国内镜像源即可（不推荐，挂梯子又有其他问题）
app isn't using AndroidX.
异常信息
```
Your app is not using AndroidX.
 To avoid potential build failures, you can quickly migrate your app by following the steps on
https://docs.flutter.dev/release/breaking-changes/androidx-migration
```
简单说明就是，android支持库（旧版：Support Library）已经不维护了，Androidx作为官方新力挺项目。自己项目如果引入的库依赖旧版本支持库，就需要更新或者在.properties文件中配置说明
解决方法:
① 在android/gradle.properties文件下，添加Androidx库的配置
```
# 启用 AndroidX 库的使用
android.useAndroidX=true

# 启用 Jetifier（自动将旧的依赖转换为 AndroidX 兼容版本）
android.enableJetifier=true
```
② 在build.gradle（或build.gradle.kts）中，添加目标 SDK 版本 (targetSdkVersion) 符合现代要求，通常建议使用当前 Flutter 版本推荐的值（例如 33 或 34）：
```
defaultConfig
{
mindSdkVersion 21
targetSdkVersion 34
}
```
③ 最后清理缓存以及重启项目
```
flutter clean
flutter run
```
java/jvm环境 & gradle 相关的依赖异常
由于gradle是基于java依赖，且flutter官网安装教程项目就是基于gradle管理，有时候会因本地jdk环境配置版本不符合gradle要求的版本，或下载的Java依赖包时出错（往往是没有通过flutter doctor诊断就直接配置Flutter项目）等等导致的异常。不管怎么样，核心还是要处理依赖包
例如：遇到Exception in thread "main" java.util.zip.ZipException: zip END header not found
（我本地已经配置好了jdk环境）依赖包下载问题，清理缓存重新下载
解决方法：
① 清理gradle仓库
（类似maven，gradle也会在用户文件夹下创建一个.gradle\wrapper\dists文件夹）
找到并且删除gradle-xxx依赖包
② 清理gradle缓存
旧版本还需要清理下.gradle\wrapper\caches目录
③重新获取Dart/Flutter包
```
# 获取可运行模拟环境
flutter pub get
# gradle自动下载依赖
flutter run
```

👏最佳实践：
我采用的方案是，手动删除gradle下载的依赖包，然后对照着
distributionUrl后面的版本号
(路径：/项目根目录/gradle/wrapper/gradle-wrapper.properties中变量distributionUrl)，
手动从源地址(https://services.gradle.org/distributions/)下载zip包，然后直接丢进对应版本文件夹

👀补充：
① gradle默认是用浏览器下载，在download等待过程，查看gradle的仓库可以看到.part和.lock文件这两个临时文件；不如借助idm等下载器下好zip包放在对应版本文件夹，运行flutter run会自行检查并且跳过下载过程
② 默认的https\😕/services.gradle.org/distributions下载环境有时候会因为国内网络问题屏蔽下载，可以切换成国内镜像资源：
例如：https://mirrors.aliyun.com/macports/distfiles/gradle/(阿里云)
(添加网址的时候，注意反斜杠)

posted @ 2025-11-23 06:17 Bingo39 阅读(10) 评论(0) 收藏举报

刷新页面返回顶部

Bingo39

Flutter 问题诊断-0.1

安装情况

flutter doctor 诊断

公告