2025-07-17

flutter环境配置

# 1. 环境安装

1.1 android-studio 下载 (opens new window)
1.2 android-studio 安装

1.2.1 注意事项：

1.2.2 设置 android-studio sdk 的环境变量

前置条件安装了 android-studio 并下载了 sdk

[X] Android toolchain - develop for Android devices X cmdline-tools component is missing.

# E:\new-insstall\sdk 为你自己的安装sdk路径
flutter config --android-sdk "E:\new-insstall\sdk"

#系统环境变量的Path中新增

"E:\new-insstall\sdk" # sdk路径
"E:\new-insstall\sdk\platform-tools" # adb路径
"E:\new-insstall\sdk\emulator" # emulator模拟器路径

1.2.3 系统环境变量--新增

国内镜像配置 (opens new window)

变量名：PUB_HOSTED_URL
变量值：https://pub.flutter-io.cn

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

1.2.4 Android 环境的错误

Gradle 相关的错误，错误类型为 java.util.zip.ZipException: zip END header not found。修改项目中 android/gradle/wrapper/gradle-wrapper.properties 文件，将 distributionUrl 指向你本地解压后的文件，如下：

# android\gradle\wrapper\gradle-wrapper.properties
distributionUrl=file:///D:/your_file_path/gradle-8.12-all.zip

# 腾讯云  https://mirrors.cloud.tencent.com/gradle/gradle-8.12-all.zip
# 阿里云  https://mirrors.aliyun.com/gradle/gradle-8.12-all.zip

"Opening Java Projects" 提示通常与 Android Studio 的 Java 项目初始化或 Gradle 构建过程有关。这一过程可能会因为多种原因（如 Gradle 配置错误、依赖下载失败或 Android Studio 插件问题）而卡住解决方式如下：

Build, Execution, Deployment>Build Tool>Gradle 路径下，下载 Gradle 包，下载地址：https://gradle.org/releases/
编辑 android/build.gradle.kts，确保使用最新稳定版本，如下：

buildscript {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        maven { url = uri("https://maven.aliyun.com/repository/google") }
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.7.3")   // 新增配置
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0")  // 新增配置
    }
}

allprojects {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        maven { url = uri("https://maven.aliyun.com/repository/google") }
        google()
        mavenCentral()
    }
}
上述几个地址是阿里云的镜像地址，可以加快依赖下载速度。

编辑 android/gradle.properties 如下：

org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
# org.gradle.jvmargs=-Xmx2048M -Dfile.encoding=UTF-8 -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStore=none -Djavax.net.ssl.trustStorePassword=changeit
android.useAndroidX=true
systemProp.gradle.internal.http.disableHostnameVerification=true

android.enableJetifier=true

# 核心配置：禁用Kotlin增量编译，彻底解决 Daemon compilation failed 崩溃
org.gradle.caching=false
org.gradle.parallel=false
kotlin.incremental=false
kotlin.incremental.android=false
kotlin.caching.enabled=false

# 禁用gradle增量编译，修复缓存冲突
org.gradle.configureondemand=false
android.injected.testOnly=false

# Flutter国内镜像，保留你的配置
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
PUB_HOSTED_URL=https://pub.flutter-io.cn

1.2.5 启动虚拟机

找到虚拟机位置，虚拟机位于 android-studio sdk 目录下，如：E:\new-insstall\sdk\emulator

E:\new-insstall\sdk\emulator\emulator.exe  -netdelay none -netspeed full -avd    Pixel_3

说明：
-netdelay none :设置模拟器的网络延迟时间，默认为 none，就是没有延迟。
-netspeed full: 设置网络加速值，full代表全速
Pixel_3: 虚拟机名称，如：Pixel 3  ** 虚拟机名字的空格使用下划线连接 **

# 2. 缓存文件配置（很重要）

缓存文件和项目文件最好在同一个盘符，这个文件很大

在「用户变量」中新建两个变量：
1. 变量名：PUB_CACHE → 变量值：F:\xxx\pub_cache  不设置环境变量的默认位置：C:\Users\Administrator\AppData\Local\Pub
2. 变量名：GRADLE_USER_HOME → 变量值：F:\xxx\gradle_cache   不设置环境变量的默认位置：C:\Users\Administrator\.gradle
3. 管理员终端执行：  taskkill /F /IM java.exe /T && taskkill /F /IM gradle.exe /T  删除进程
4. 关闭vscode，cmd，删掉默认位置：C:\Users\Administrator\.gradle，C:\Users\Administrator\AppData\Local\Pub这两个文件
5. 最好重启电脑

# 3. 基础命令

https://www.jianshu.com/p/87052f809556
flutter doctor  # 检查环境
flutter doctor   --android-licenses # 安装android sdk的license

flutter clean # 清理项目级冗余缓存

gradle clean --refresh-dependencies # 清理Gradle全局冗余缓存（核心命令）

# 插件库：https://pub.dev/packages/http/install
flutter pub  add  <插件名称>  # 安装插件，如：flutter pub add http

f5 # debug模式断点运行

flutter analyze  # 检查代码规范
flutter pub cache repair # 修复依赖库

flutter pub get #安装依赖库

flutter pub outdated # 查看具体是哪些库卡住了
flutter pub upgrade --major-versions  #尝试自动修复： 如果冲突不严重，可以让 Flutter 自动尝试更新 pubspec.lock

flutter packages get  #Flutter 1.x 时代的旧命令，功能与flutter pub get 相同，但在新版本中已被弃用（仍保留向后兼容）

flutter devices  # 查看flutter可运行的设备如下：
- Windows (desktop) • windows • windows-x64    • Microsoft Windows [版本 10.0.26100.4349]
- Chrome (web)      • chrome  • web-javascript • Google Chrome 138.0.7204.101
- Edge (web)        • edge    • web-javascript • Microsoft Edge 131.0.2903.146

flutter run  -d <平台>  # 平台：windows、chrome、edge ； 使用flutter devices获取平台
flutter run -d all  # 运行所有可运行的设备
flutter run -d windows  # 运行windows设备
flutter run -d chrome  # 运行chrome设备

- r 键：点击后热加载，也就算是重新加载吧。
- R 键：热重启项目
- p 键：显示网格，这个可以很好的掌握布局情况，工作中很有用。
- o 键：切换android和ios的预览模式。
- q 键：退出调试预览模式。

2.1 低版本运行

# 使用 --no-sound-null-safety 选项（针对 Dart 2 项目）忽略 SDK 约束（不推荐）
#临时忽略版本检查，但可能导致运行时错误：
flutter run --no-sound-null-safety

# 升级所有依赖到兼容版本 (老项目很重要)
flutter pub upgrade --major-versions

# 4. fvm 管理 flutter 版本，不能使用 gitbash 运行 fvm 命令

dart pub global activate fvm  # 安装fvm

dart pub global deactivate fvm  # 卸载 fvm

# 安装并使用 Flutter 2.x
fvm install 2.10.5
fvm use 2.10.5

# 通过 FVM 执行命令
fvm flutter pub get
fvm flutter run

fvm releases # flutter历史版本

where fvm # fvm的安装位置获取
# 配置环境变量,系统环境变量的Path中添加：
C:\Users\Administrator\AppData\Local\Pub\Cache\bin

# 指定本地压缩包路径安装flutter：
fvm install 2.10.5 --archive-path="D:\flutter_windows_2.10.5-stable.zip"

# 5. 插件

- 4.1.1 Awesome Flutter Snippets  //代码片段
- 4.1.2 Flutter

如：快速生成 stlssh 代码片段

# 6. 5.布局

基础布局使用 (opens new window)

# 7. 开发文档

第三方文档 (opens new window) 请求库 (opens new window) 官方文档 (opens new window)

# 8. 7.工具

wifi 真机调试 (opens new window)

上次更新: 2026-01-18