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

灯火不休2026-07-18 9:42

涵盖 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[变种名][构建类型]

bash 复制代码 
# 渠道名 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 补充小技巧

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

二、Gradle 同步与依赖刷新

2.1 手动同步命令

等效于 AS 界面「Sync Now」：

bash 复制代码 
# 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 前置说明

  1. 先确保环境正常：flutter doctor
  2. 所有命令在 Flutter 项目根目录 执行
  3. 打包前建议先清理缓存：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 常用组合命令（生产标准流程）

bash 复制代码 
# 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 完整解析

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

Dart 读取示例：

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 相关（多环境 / 多渠道）

bash 复制代码 
# 运行
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 系列（注入常量）

bash 复制代码 
# 单个常量
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 进阶组合命令

bash 复制代码 
# 预发环境 + 注入域名 + 指定设备
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

六、使用建议

  1. 日常开发 ：改代码 → flutter run 运行，用 r 热重载；改 pubspec.yaml 必执行 flutter pub get。
  2. 打包发布 ：固定用组合命令 flutter clean && flutter pub get && 对应打包指令。
  3. 编译报错 ：先 flutter clean 再重试；依赖异常执行 flutter pub cache repair。
  4. 原生层报错 ：切到 android 目录，使用原生 gradlew 命令排查。
  5. 混合项目 ：在 Flutter 项目 android/ 目录下可直接执行原生 Gradle 命令。
bash 复制代码 
cd android
gradlew clean
gradlew assembleDebug
cd ..
相关推荐
杉氧1 小时前
Ktor 全栈之路 (5)：JWT 认证全流程实战 —— 打造安全通信闭环
android·架构·kotlin
️学习的小王2 小时前
Python + MySQL 学生信息管理系统实战教程
android·python·mysql
帅次2 小时前
Android 高级工程师面试：Flutter 路由导航 近1年高频追问 18 题
android·flutter·面试
alexhilton10 小时前
MVI模式的完整历史、误解和现代Android范式
android·kotlin·android jetpack
心中有国也有家16 小时前
AtomGit Flutter 鸿蒙客户端：Canvas 绘制进阶-路径、渐变与混合模式
android·javascript·flutter·华为·harmonyos
hunterandroid17 小时前
WorkManager 可靠性实战：唯一任务、重试与幂等设计
android·前端
程序员老刘17 小时前
Android 17的10个AI功能，国内用户真正能用的有几个？
android·flutter·ai编程
花开彼岸天~18 小时前
鸿蒙应用开发实战【94】— 实战多卡号场景管理最佳实践
android·华为·harmonyos·鸿蒙系统
用户416596736935518 小时前
视频源文件音频轨异常分析记录
android
热门推荐
012026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片02GitHub 镜像站点03AI科技热点日报 | 2026年07月01日04幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南05AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路06国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？082026年AI技术突破与产业落地全景：从GPT-5到多模态智能体的新纪元09Codex 下载安装指南：Windows 和 macOS 官方版下载102026 年 AI 大模型 & AI 编程工具实战全总结