Android Studio & Flutter 构建命令完全指南涵盖 Android 原生 Gradle 命令与 Fl

涵盖 Android 原生 Gradle 命令与 Flutter 构建命令，适用于 Windows / Mac / Linux 平台，所有命令均在项目根目录的 Terminal 中执行。

一、Android 原生 Gradle 命令

1.1 Gradle 与 Gradle Wrapper 的区别

命令	说明	推荐度
`gradle`	全局安装的 Gradle 本体命令，需手动安装对应版本、配置环境变量	❌ 不推荐
`gradlew`	项目自带的 Gradle Wrapper 启动脚本（`gradlew` / `gradlew.bat`），版本由项目锁定，自动下载	✅ Android 标准用法

为什么必须用 gradlew？

版本兼容：Android 项目对 Gradle 版本有强绑定，gradlew 自动使用项目预设版本，避免版本不一致导致编译失败。
团队协作：团队成员拉取代码后直接执行 gradlew 即可构建，环境零差异。
配置隔离：gradlew 读取项目内配置，全局 gradle 走系统配置，容易互相干扰。

执行逻辑：gradlew clean → 读取 gradle-wrapper.properties → 检查本地对应 Gradle 版本 → 没有则自动下载 → 执行 clean 任务。

Windows：执行 gradlew（即 gradlew.bat） Mac/Linux：执行 ./gradlew（首次需 chmod +x gradlew）

1.2 基础通用命令

功能	命令（Windows）	命令（Mac/Linux）
清理构建缓存	`gradlew clean`	`./gradlew clean`
查看所有可用任务	`gradlew tasks`	`./gradlew tasks`
查看 app 模块依赖树	`gradlew app:dependencies`	`./gradlew app:dependencies`
离线模式执行	任意命令后加 `--offline`	同上

gradlew clean 删除编译产物、缓存文件，解决编译异常、打包旧残留问题。

1.3 APK 打包命令

Android 分 Debug 测试包 和 Release 正式包。

功能	命令	输出路径
打 Debug 测试包	`gradlew assembleDebug`	`app/build/outputs/apk/debug/`
打 Release 正式包	`gradlew assembleRelease`	`app/build/outputs/apk/release/`
同时打 Debug + Release	`gradlew assemble`	—
清理后打 Debug 包	`gradlew clean assembleDebug`	—
清理后打 Release 包（标准流程）	`gradlew clean assembleRelease`	—

Release 包必须先配置签名文件，否则打包失败。

1.4 AAB 打包（Google Play 上架专用）

Android App Bundle 是谷歌官方推荐上架格式，体积更小。

功能	命令
打 Release 版 AAB	`gradlew clean bundleRelease`
打 Debug 版 AAB	`gradlew bundleDebug`

输出路径：app/build/outputs/bundle/release/

1.5 安装 / 运行 APK

功能	命令
编译 + 安装 Debug 包到设备	`gradlew installDebug`
卸载 Debug 包	`gradlew uninstallDebug`
卸载 Release 包	`gradlew uninstallRelease`
运行（等效 Run 按钮）	`gradlew run`

1.6 编译校验 & 检查

功能	命令
仅编译代码（快速查语法错误）	`gradlew compileDebugSources` / `gradlew compileReleaseSources`
Lint 代码静态检查	`gradlew lint`（报告：`app/build/reports/lint-results.html`）
本地单元测试	`gradlew test`
设备仪器测试	`gradlew connectedAndroidTest`

1.7 多渠道 / 多变种打包（Product Flavor）

格式：assemble[变种名][构建类型]

# 渠道名 xiaomi，构建类型 Release
gradlew assembleXiaomiRelease

1.8 常用参数

参数	作用
`-q`	精简日志，只看关键输出
`--info`	详细日志，排查打包报错
`--stacktrace`	打印完整堆栈，编译崩溃必加
`--parallel`	并行构建，多模块项目加速
`--offline`	离线模式，无网络时使用

1.9 命令速查表

功能	命令
清理缓存	`gradlew clean`
打 Debug APK	`gradlew assembleDebug`
打 Release APK	`gradlew assembleRelease`
标准正式打包	`gradlew clean assembleRelease`
打 Release AAB	`gradlew clean bundleRelease`
安装 Debug 包	`gradlew installDebug`
代码 Lint 检查	`gradlew lint`
查看依赖	`gradlew app:dependencies`

1.10 补充小技巧

命令输错、打包卡住：先执行 gradlew clean 再重试。
签名报错：检查 build.gradle(Module) 中 signingConfigs 签名配置。
Mac 权限问题：首次执行 chmod +x gradlew。

二、Gradle 同步与依赖刷新

2.1 手动同步命令

等效于 AS 界面「Sync Now」：

# Windows
gradlew --refresh-dependencies

# Mac/Linux
./gradlew --refresh-dependencies

2.2 使用场景

场景	说明
修改 `build.gradle` / `gradle.properties`	改依赖、SDK 版本、签名、渠道、仓库地址等
依赖缓存异常	报 `Failed to resolve`、版本错乱、旧版本残留
切换分支 / 拉取团队代码	别人改了 Gradle 配置，本地缓存旧
升级 Android Studio / Gradle	版本不匹配、构建卡住、诡异报错
纯命令行构建（CI/CD）	无图形界面，只能用命令刷新
顽固问题	`gradlew clean --refresh-dependencies` 组合执行

2.3 与 `clean` 的区别

命令	作用
`gradlew clean`	只删除编译产物、APK、class，不碰依赖和 Gradle 配置
`gradlew --refresh-dependencies`	只刷新依赖、Gradle 配置、仓库，不删编译产物

简单记忆：

改代码/资源编译报错 → clean
改 Gradle 配置/依赖/版本拉取失败 → --refresh-dependencies

三、Flutter 构建命令

3.1 前置说明

先确保环境正常：flutter doctor
所有命令在 Flutter 项目根目录 执行
打包前建议先清理缓存：flutter clean

3.2 通用基础命令

功能	命令
清理构建缓存	`flutter clean`
检查环境 & 依赖	`flutter doctor`
拉取项目依赖	`flutter pub get`
强制刷新依赖缓存	`flutter pub upgrade` / `flutter pub cache repair`
运行项目	`flutter run`
查看设备列表	`flutter devices`
实时查看日志	`flutter logs`
代码静态检查	`flutter analyze`

flutter pub get 对应 Android 的 Sync Now / gradlew --refresh-dependencies。 flutter clean 对应 Android 的 gradlew clean。

3.3 Android 平台打包

功能	命令	输出路径
Debug 测试 APK	`flutter build apk --debug`	`build/app/outputs/flutter-apk/app-debug.apk`
Release 正式 APK	`flutter build apk --release`	`build/app/outputs/flutter-apk/app-release.apk`
仅 arm64 架构（推荐）	`flutter build apk --release --target-platform android-arm64`	—
仅 arm32 架构	`flutter build apk --release --target-platform android-arm`	—
AAB（Google Play 上架）	`flutter build appbundle --release`	`build/app/outputs/bundle/release/app-release.aab`
多渠道打包	`flutter build apk --release --flavor 渠道名`	—

Release 包必须提前配置 Android 签名。

3.4 iOS 平台打包（仅 Mac）

功能	命令
模拟器调试包	`flutter build ios --debug`
真机 Release 包	`flutter build ios --release`
iOS Flavor 打包	`flutter build ios --release --flavor 环境名`

flutter build ios --release 后，用 Xcode 打开 ios/Runner.xcworkspace → 归档 → 导出 IPA。

3.5 桌面 / 网页端打包

平台	命令
Web	`flutter build web --release`（产物：`build/web`）
Windows	`flutter build windows --release`
macOS	`flutter build macos --release`
Linux	`flutter build linux --release`

3.6 安装 / 运行命令

功能	命令
连接设备运行	`flutter run`
只安装不启动	`flutter install`
卸载应用	`flutter uninstall`
指定 Flavor 运行	`flutter run --flavor dev --debug`

3.7 常用组合命令（生产标准流程）

# Android Release APK
flutter clean && flutter pub get && flutter build apk --release

# Google Play AAB
flutter clean && flutter pub get && flutter build appbundle --release

# Web 打包
flutter clean && flutter pub get && flutter build web --release

3.8 关键参数速查

参数	作用
`--debug`	调试包，可断点、日志完整
`--release`	正式包，代码混淆、压缩、性能优化
`--flavor xxx`	指定多环境/多渠道变种
`--target-platform`	指定 Android CPU 架构
`--no-codesign`	iOS 编译不签名，后续手动签名

四、Flutter 进阶命令详解

4.1 `flutter run` 完整解析

flutter run --flavor staging --dart-define=DEV_HOST=xxx

--flavor staging：指定 Flavor 为预发环境，加载对应原生配置、签名、渠道、包名、图标等。
--dart-define=DEV_HOST=xxx：编译期注入环境变量，Dart 代码中通过 String.fromEnvironment('DEV_HOST') 读取。

Dart 读取示例：

const String devHost = String.fromEnvironment('DEV_HOST', defaultValue: '');
const bool isDebug = bool.fromEnvironment('ENABLE_LOG', defaultValue: false);
const int port = int.fromEnvironment('PORT', defaultValue: 8080);

4.2 Flavor 相关（多环境 / 多渠道）

# 运行
flutter run --flavor dev
flutter run --flavor staging
flutter run --flavor prod

# 打包
flutter build apk --release --flavor staging
flutter build appbundle --release --flavor prod

前提：必须在 android/build.gradle 和 iOS 工程中配置好对应 Flavor。

4.3 `--dart-define` 系列（注入常量）

# 单个常量
flutter run --dart-define=API_BASE_URL=https://api.test.com

# 多个常量
flutter run --dart-define=API_HOST=https://staging.xxx.com --dart-define=APP_ENV=staging

# 打包时使用
flutter build apk --release --flavor prod --dart-define=API_HOST=https://prod.xxx.com

4.4 常用附加参数

参数	作用
`--no-sound-null-safety`	关闭空安全（老项目兼容）
`-d 设备ID`	指定设备运行
`--profile`	Profile 模式（性能分析）
`--release`	Release 模式运行
`--no-hot`	不开启热重载
`-q`	静默运行，精简日志

4.5 进阶组合命令

# 预发环境 + 注入域名 + 指定设备
flutter run --flavor staging --dart-define=API_HOST=https://staging-api.com -d 设备ID

# 生产包打包标准命令
flutter clean && flutter pub get && flutter build apk --release --flavor prod --dart-define=API_HOST=https://prod-api.com

# 预编译检查（不启动）
flutter run --flavor dev --dart-define=API_HOST=xxx --no-run

4.6 关键说明

--dart-define 是编译期常量，适合传域名、环境标识、功能开关；不要传密钥或私密令牌（可被逆向提取）。
--flavor 控制原生层（包名、签名、渠道、图标）；--dart-define 控制 Dart 业务层（接口域名、功能开关）。
Flutter --flavor ≈ Android productFlavors
Flutter --dart-define ≈ Android buildConfigField

五、Flutter ↔ Android 命令对照表

场景	Flutter 命令	Android 原生命令
清理编译缓存	`flutter clean`	`gradlew clean`
同步依赖/配置	`flutter pub get`	Sync Now / `gradlew --refresh-dependencies`
打 Debug 包	`flutter build apk --debug`	`gradlew assembleDebug`
打 Release 包	`flutter build apk --release`	`gradlew assembleRelease`
查看日志	`flutter logs`	Logcat

六、使用建议

日常开发：改代码 → flutter run 运行，用 r 热重载；改 pubspec.yaml 必执行 flutter pub get。
打包发布：固定用组合命令 flutter clean && flutter pub get && 对应打包指令。
编译报错：先 flutter clean 再重试；依赖异常执行 flutter pub cache repair。
原生层报错：切到 android 目录，使用原生 gradlew 命令排查。
混合项目：在 Flutter 项目 android/ 目录下可直接执行原生 Gradle 命令。

cd android
gradlew clean
gradlew assembleDebug
cd ..

Android Studio & Flutter 构建命令完全指南