Flutter 开发环境配置文档

环境信息项目版本操作系统Debian GNU/Linux 13 (trixie)Flutter3.44.9 (stable)Dart3.12.2目标平台Android 8.1.0 (arm64)2026/8/11安装路径Flutter SDK:/usr/local/flutter项目目录:~/AndroidStudioProjects/环境变量~/.bashrc中添加bash# Flutter export PATH/usr/local/flutter/bin:$PATH export PUB_HOSTED_URLhttps://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URLhttps://storage.flutter-io.cn配置完后执行source ~/.bashrc或重启终端生效。安装步骤1. 下载 SDK从腾讯镜像下载约 1.5GBbashcurl -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国内建议使用镜像站官方 Google Storage 下载极慢甚至超时。如果不清楚最新版本号可先访问https://mirrors.cloud.tencent.com/flutter/flutter_infra_release/releases/releases_linux.json查看版本列表。下载速度约 3.5MB/s耗时约 6 分钟网速不佳时可能更长。2. 验证完整性可选bashcd /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; djson.load(sys.stdin); cur[r for r in d[releases] if r[version]3.44.9][0]; print(cur[sha256], flutter_3.44.9.tar.xz) )若下载中断或文件损坏可删除flutter_3.44.9.tar.xz后重下无需重复解压。3. 解压到系统目录bashcd /usr/local sudo tar -xf /tmp/flutter_3.44.9.tar.xz文件权限坑tar解压后的文件属主为 root但flutter命令执行时会向 SDK 目录写入bin/cache/等缓存文件。普通用户执行flutter命令可能因权限不足报错。解决方法选其一方法一推荐给用户添加写权限仅开放 cache 目录bashsudo chown -R $USER:$USER /usr/local/flutter方法二每次执行时用sudo flutter但不推荐后续pub get等操作可能有权限残留问题方法三将 SDK 解压到用户目录~/flutter无需改权限但需注意 PATH 配置4. 清理压缩包bashrm -f /tmp/flutter_3.44.9.tar.xz5. 验证安装bashflutter --version # Flutter 3.44.9 · channel stable · ... # Dart 3.12.2若提示flutter: command not found检查 PATH 是否包含/usr/local/flutter/bin确认~/.bashrc已加载。Android SDK 配置编译 Android 应用必需Flutter 编译 Android 需要依赖 Android SDK。建议通过 Android Studio 安装 SDK或手动下载 command-line tools。环境变量~/.bashrcbashexport ANDROID_HOME$HOME/Android/Sdk export PATH$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$PATH接受 licenses首次编译前必须执行bashflutter doctor --android-licenses按提示输入y接受所有 license。如果这一步卡住或报网络错误可能是镜像源问题需确保PUB_HOSTED_URL和FLUTTER_STORAGE_BASE_URL已配置。检查环境bashflutter doctor确保 Android SDK、Android Studio 等标记为✓。版本升级升级时保留旧版本作为回退bash# 备份旧版本 sudo mv /usr/local/flutter /usr/local/flutter_旧版本号_backup # 解压新版本 cd /usr/local sudo tar -xf /tmp/flutter_新版.tar.xz项目构建清理旧缓存升级 SDK 后项目中原有的.dart_tool、.gradle可能包含旧版本信息建议删除bashrm -rf .dart_tool .gradle build坑.gradle目录在项目根目录下删除后重新pub get会自动重建不会影响代码。如果不清除可能出现gradle version mismatch等错误。获取依赖bashflutter pub get国内用户需确保PUB_HOSTED_URL已配置否则访问 pub.dev 可能超时。编译 APKbashflutter build apk --release产物位置build/app/outputs/flutter-apk/app-release.apk若编译失败先执行flutter clean清理所有构建缓存再重新pub get。常见问题1. PATH 优先级问题若 Android Studio 内置了旧版本 Flutter需确保/usr/local/flutter/bin在 PATH 中排在 Android Studio 路径之前。查看当前 Flutter 路径bashwhich flutter若指向错误路径检查~/.bashrc中 PATH 的配置顺序。2. 镜像源超时国内网络需配置 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL否则pub get和 SDK 下载会超时。3. 升级后报版本冲突删除.dart_tool、.gradle、build目录后重新pub get可解决。4. 权限错误解压后若未改属主执行flutter命令可能报Permission denied或flutter: command not found需执行sudo chown -R $USER:$USER /usr/local/flutter。5. 下载中断下载 SDK 时若中断压缩包不完整解压会失败。重新下载前需删除已存在的部分文件。6. Android license 状态异常执行flutter doctor时若提示✗ Android license status unknown执行flutter doctor --android-licenses重新接受 license。若始终失败可能是网络问题导致 Android SDK 管理器无法访问 Google 服务需配置代理或换镜像。磁盘空间要求内容大小SDK 压缩包~1.5GBSDK 解压后~2.5GB项目缓存~200MBAndroid SDK~2-3GB视 platform 版本数量实际所需空间取决于已安装的 Android platform 版本数量建议/usr/local和~/Android/Sdk所在分区预留至少 5-8GB。