Flutter 开发环境配置文档

环境信息

2026/8/11

安装路径

• Flutter SDK:/usr/local/flutter

• 项目目录:~/AndroidStudioProjects/

环境变量

~/.bashrc中添加：

bash

# Flutter export PATH="/usr/local/flutter/bin:$PATH" export PUB_HOSTED_URL="https://pub.flutter-io.cn" export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

配置完后执行source ~/.bashrc或重启终端生效。

安装步骤

1. 下载 SDK

从腾讯镜像下载（约 1.5GB）：

bash

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"

国内建议使用镜像站，官方 Google Storage 下载极慢甚至超时。如果不清楚最新版本号，可先访问https://mirrors.cloud.tencent.com/flutter/flutter_infra_release/releases/releases_linux.json查看版本列表。

下载速度约 3.5MB/s，耗时约 6 分钟，网速不佳时可能更长。

2. 验证完整性（可选）

bash

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); 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. 解压到系统目录

bash

cd /usr/local sudo tar -xf /tmp/flutter_3.44.9.tar.xz

文件权限坑：tar解压后的文件属主为 root，但flutter命令执行时会向 SDK 目录写入bin/cache/等缓存文件。普通用户执行flutter命令可能因权限不足报错。

解决方法（选其一）：

• 方法一（推荐）：给用户添加写权限，仅开放 cache 目录：

  bash

  sudo chown -R $USER:$USER /usr/local/flutter

• 方法二：每次执行时用sudo flutter，但不推荐（后续pub get等操作可能有权限残留问题）

• 方法三：将 SDK 解压到用户目录（~/flutter），无需改权限，但需注意 PATH 配置

4. 清理压缩包

bash

rm -f /tmp/flutter_3.44.9.tar.xz

5. 验证安装

bash

flutter --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。

环境变量（~/.bashrc）：

bash

export ANDROID_HOME="$HOME/Android/Sdk" export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$PATH"

接受 licenses（首次编译前必须执行）：

bash

flutter doctor --android-licenses

按提示输入y接受所有 license。如果这一步卡住或报网络错误，可能是镜像源问题，需确保PUB_HOSTED_URL和FLUTTER_STORAGE_BASE_URL已配置。

检查环境：

bash

flutter 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可能包含旧版本信息，建议删除：

bash

rm -rf .dart_tool .gradle build

坑：.gradle目录在项目根目录下，删除后重新pub get会自动重建，不会影响代码。如果不清除，可能出现gradle version mismatch等错误。

获取依赖

bash

flutter pub get

国内用户需确保PUB_HOSTED_URL已配置，否则访问 pub.dev 可能超时。

编译 APK

bash

flutter 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 路径：

bash

which 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 服务，需配置代理或换镜像。

磁盘空间要求

实际所需空间取决于已安装的 Android platform 版本数量，建议/usr/local和~/Android/Sdk所在分区预留至少 5-8GB。