Flutter 折腾记录（环境）

日期: 2026-08-11 机器: ryzen5-5500u · Debian 13 (trixie) 目的: Flutter Android 开发环境搭建 + 升级 + 用 Waydroid 无模拟器真跑 APK

---

当前版本（2026-08-11）

组件	版本
Flutter	3.44.9 (stable) · 2026-08-05
Dart	3.12.2
DevTools	2.57.0
安装路径	/usr/local/flutter
可用设备	WayDroid(Android 13 API 33) · Linux desktop · Chrome

之前是 3.29.3 + Dart 3.7.3，因 video_player: ^3.0.2 要求 Dart 3.8.2+ 才升级。

---

升级过程（3.29.3 → 3.44.9）

1. 下载

腾讯镜像下载（约 3.5MB/s，1.5GB，6 分钟）：

curl -L -o /tmp/flutter_3.44.9.tar.xz \
  "https://mirrors.cloud.tencent.com/flutter/flutter_infra_release/releases/stable/linux/flutter_linux_3.44.9-stable.tar.xz"

2. 校验 SHA256（可选）

cd /tmp
sha256sum -c - <<< "$(curl -s --max-time 15 \
  'https://mirrors.cloud.tencent.com/flutter/flutter_infra_release/releases/releases_linux.json' | \
  python3 -c "import json,sys; d=json.load(sys.stdin); r=[x for x in d['releases'] if x['version']=='3.44.9'][0]; print(r['sha256'],'flutter_3.44.9.tar.xz')")"

3. 替换旧版

# 备份旧版（可选）
mv /usr/local/flutter /usr/local/flutter_3.29.3_backup

# 解压新版
cd /usr/local
sudo rm -rf /usr/local/flutter
sudo tar -xf /tmp/flutter_3.44.9.tar.xz
rm -f /tmp/flutter_3.44.9.tar.xz

4. 环境变量（~/.bashrc）

export PATH="/usr/local/flutter/bin:$PATH"
export PUB_HOSTED_URL="https://mirrors.tuna.tsinghua.edu.cn/dart-pub"   # pub 依赖
export FLUTTER_STORAGE_BASE_URL="https://mirrors.huaweicloud.com/flutter"  # Flutter 引擎构件
# 注意: 也有配置是 pub.flutter-io.cn / storage.flutter-io.cn, 三选一, 如下图

⚠️ 清华 pub 与华为云 Flutter 镜像可混用；两者都绕开 GitHub/storage.googleapis.com 保证国内速度。

5. 重新编译

cd <项目目录>
rm -rf .gradle .dart_tool build   # 升级后必清理, 否则版本冲突
flutter pub get
flutter build apk --release

---

构建链 & Gradle（大坑合集）

源镜像

Flutter 项目默认的 Gradle 仓库是 google() / mavenCentral()（国内慢），改用阿里云：

• Gradle 全局 init（~/.gradle/init.gradle.kts）：

settingsEvaluated {
    pluginManagement {
        repositories {
            maven(url = "https://maven.aliyun.com/repository/gradle-plugin")
            maven(url = "https://maven.aliyun.com/repository/google")
            maven(url = "https://maven.aliyun.com/repository/central")
        }
    }
}

坑1: Gradle 9 的 FAIL_ON_PROJECT_REPOS

新版 Gradle 默认禁止项目里再声明 allprojects {}/buildscript 仓库（会直接报 FAIL_ON_PROJECT_REPOS），解决：

• 去掉 build.gradle.kts 里的 allprojects { repositories {...} }
• 依赖统一走 settings.gradle.kts 的 dependencyResolutionManagement + RepositoriesMode.PREFER_PROJECT，其中加入阿里云镜像。

坑2: 华为云镜像缺 io.flutter debug 构件（未解决）

• flutter build apk --release 能用（release 构件齐全）。
• flutter run -d waydroid（debug）会从 mirrors.huaweicloud.com/flutter 取 io.flutter:flutter_embedding_debug 等，华为云镜像缺失 → 构建失败。
• 官方源 https://storage.googleapis.com 有但直连极慢（10 分钟超时）。
• 对策方向：挂代理走官方源补齐；或找完整镜像；后续再试。

adb 调试链

adb devices
flutter devices   # WayDroid x86 64 Device (mobile) → 192.168.240.112:5555
flutter run -d waydroid

APK 安装也可直接 adb install -r -d app-release.apk。

---

常用命令速查

flutter --version          # 版本
flutter doctor             # 环境健康检查
flutter devices            # 可用设备
flutter pub get            # 拉依赖
flutter analyze            # 静态检查
flutter build apk --release  # 出正式 APK
flutter run -d <device>    # 运行(debug)

---

注意事项

1. PATH 顺序：/usr/local/flutter/bin 要在前面，避免被 Android Studio 内置旧版 Flutter 覆盖。
2. 空间: Flutter SDK 约 1.5GB tar / 解压 2.5GB；另 pub-cache 1.1G、gradle cache 2.4G。别轻易删 pub-cache/gradle cache（重下更慢）。
3. 镜像选择：腾讯镜像只在下载 SDK 包时用；日常 pub 用清华，Flutter 引擎用华为云。
4. Waydroid 设备：见《Waydroid折腾记录_2026-08-11.md》，微信/ARM-only 应用受限。