Flutter 项目快速入门

今日無事
1,021 阅读5分钟

1 开发工具

在开始 Flutter 开发之前，第一步是把几个关键工具准备好。安装顺序建议是：Android Studio → Jave JDK → Gradle → Flutter SDK。

1.1 Android Studio

Android Studio 是 Android 开发常用的 IDE，相当于“工作台”。第一次启动它的时候，会自动下载很多 Android SDK 组件，这些是后续开发不可或缺的工具。

它会下载的主要组件包括：

  • Android Emulator：Android 设备模拟器，用于在计算机上测试和运行 Android 应用程序。
  • Android SDK Build-Tools 35：用于构建、编译和打包 Android 应用程序的工具集。
  • Android SDK Platform 35：Android 平台的核心组件，包括 Android 操作系统的 API、类库和系统图像。
  • Android SDK Platform-Tools：用于与 Android 设备通信、调试和管理应用程序的工具集。
  • Sources for Android 35：包含 Android 框架的源代码，供开发人员查看和理解 Android 框架的实现细节。

1.2 Java JDK

Gradle 依赖 Java 来构建 Android 项目，所以 JDK 是必须的。可以去 Oracle 官网或者 OpenJDK 下载，推荐使用 JDK8 或 JDK17。

安装好之后，在终端输入 java -version，如果能看到版本号，就说明安装成功了。Mac 上默认安装路径在：/Library/Java/JavaVirtualMachines。

安装完成后，还需要配置环境变量，让系统和 Gradle 都能找到 Java。配置方法是编辑 shell 配置文件，例如 ~/.bash_profile 或 ~/.zshrc：

# Java 环境配置
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-24.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

保存后执行 source ~/.bash_profile 、 source ~/.zshrc 或重启设备让配置生效。这样，命令行里就能随时使用 java 或 javac。

1.3 Gradle

Gradle 是 Android 项目构建的核心工具，它负责把源码打包成 APK 或 AAR 文件。安装方式有两种：

  • Homebrew 安装：

    brew install gradle@7

  • 手动安装：去 Gradle 官网下载压缩包，解压到固定目录，然后在环境变量里配置路径。

环境变量配置示例：

# Gradle 环境
export GRADLE_HOME=/opt/homebrew/opt/gradle
export PATH=$GRADLE_HOME/bin:$PATH

安装完之后配置环境变量，就可以在任何目录下使用 gradle -v 来检查安装是否成功。Gradle 要在 JDK 配置完成之后再安装，否则可能会报 Java 找不到的错误。

1.4 Flutter SDK

Flutter SDK 是整个跨平台开发的核心。可以去 Flutter 官网或 Github 下载对应版本的 SDK，解压到一个固定路径，比如桌面或者用户目录。

安装 Flutter SDK 后，还需要在 Android Studio 的插件市场里安装 Flutter 插件和 Dart 插件。安装完成后，在 Android Studio 设置里指向 Flutter SDK 的路径，Dart SDK 会自动跟随配置。这样就可以直接在 Android Studio 里创建和运行 Flutter 项目了。

插件市场路径如下：

Android Studio → Preferences → Plugins → Marketplace → 搜索 Flutter → Install

环境变量配置如下：

# Flutter 环境
export FLUTTER_HOME=$HOME/Projects/flutter_stable
export PATH=$FLUTTER_HOME/bin:$PATH

# Flutter 国内镜像
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

配置完成后，就可以在终端里运行 flutter doctor 来检查整个 Flutter 开发环境是否准备就绪。

2 创建&运行项目

2.1 创建一个 Flutter 项目

创建项目顺序：Android Studio → New Flutter Project → Flutter Application → 配置 SDK → 填写项目信息 → Create。

具体步骤：

  1. 打开 Android Studio → File → New → New Flutter Project

  2. 选择 Flutter Application

  3. 配置 Flutter SDK 路径（如果尚未配置，需要先下载或指定 SDK 位置）

  4. 输入项目名称、存储路径和描述 → Create

  5. 等待项目生成完成，点击运行即可在模拟器或真机上看到默认计数器应用

2.2 检查环境

新创建的项目可能无法直接运行，因为系统环境变量或依赖工具（如 JDK、Android SDK、Gradle）尚未完全配置。此时，运行项目可能会提示缺少工具或版本不兼容。

因此，建议在运行项目前，先使用 flutter doctor 检查系统环境，确认 Flutter、Dart、Android Studio、Android SDK 等开发所需组件是否已正确安装并可用。

打开终端，进入任意目录，输入：

flutter doctor

当第一次运行 flutter doctor 命令时，将会下载一些必要的资源和工具来进行环境检查和配置。

flutter doctor 命令会告诉你Flutter、Dart、Android Studio、Android SDK、Xcode 等是否正常，常见错误情况包括：

  • Unable to find bundled Java version

  • 说明系统找不到 JDK，检查 JAVA_HOME 是否配置正确，并确认路径有效。

  • Flutter channel unknown 或 Unknown upstream repository：

  • 这是因为 Flutter 无法识别或确定当前所使用的Flutter通道（channel），每个通道都具有不同的特性和稳定性级别。

    flutter channel // 查看当前Flutter渠道
flutter channel stable // 切换到稳定版官方渠道
flutter upgrade// 升级Flutter到最新版本（可选）

  • cmdline-tools component is missing

  • 打开 Android Studio → Preferences → SDK Manager → SDK Tools，勾选 Android SDK Command-line Tools 并安装。

  • Android licenses status unknown

  • 运行并输入 y 接受所有协议

    flutter doctor --android-licenses

2.3 配置开发环境变量

配置环境变量的目的就是让系统知道 JDK、Android SDK、Flutter SDK 等工具的位置，这样在命令行或开发工具中就能直接调用这些工具，而不需要每次手动输入路径。

Windows 系统

在 Windows 上，配置环境变量的步骤大致如下：

  1. 右键点击 “此电脑” → 属性 → 高级系统设置 → 环境变量
  2. 在 系统变量 中找到 Path，点击 编辑
  3. 在弹出的窗口里点击 新建，分别输入 JDK、Android SDK、Flutter SDK 的路径
  4. 多个路径用 分号 ; 分隔
  5. 点击 确认 保存所有更改

配置完成后，可以打开命令行，运行 java -version、flutter doctor 等命令测试是否生效。

MacOS 系统

Mac 系统需要确认默认的 shell：

  • macOS Catalina 之前默认是 Bash
  • Catalina 及之后版本默认是 Zsh

打开终端，编辑或创建 shell 配置文件(新电脑可能没有 shell 文件)：

  • Bash：~/.bash_profile 或 ~/.bashrc
  • Zsh：~/.zshrc

然后把以下内容添加进去（根据安装路径修改）：

# Java 环境配置
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-24.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

# Gradle 环境
export GRADLE_HOME=/opt/homebrew/opt/gradle
export PATH=$GRADLE_HOME/bin:$PATH

# Flutter 环境
export FLUTTER_HOME=$HOME/Projects/flutter_stable
export PATH=$FLUTTER_HOME/bin:$PATH

# Flutter国内镜像（加速 pub get）
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# Android 环境
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$ANDROID_HOME/emulator:$PATH
export PATH=$ANDROID_HOME/tools:$PATH
export PATH=$ANDROID_HOME/tools/bin:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH

保存文件后，在终端执行让修改生效：

source ~/.bash_profile   # Bash
source ~/.zshrc          # Zsh

然后可以运行以下命令检查是否配置成功：

echo $JAVA_HOME
echo $ANDROID_HOME

3 打包与安装

开发调试成功后，下一步就是把应用打包，并安装到手机或模拟器上进行测试或发布。打包流程可以分为：

  1. 跨平台打包

  2. 原生打包

  3. Android 原生打包（Gradle） 

  4. iOS 原生打包（Xcode） 

  5. 安装到设备或模拟器

使用 Flutter 或 Gradle 打包都可以，区别是 Flutter 打包更适合跨平台，Gradle/Xcode 更适合原生项目自定义构建流程。

3.1 跨平台打包

Flutter 提供一条命令就能同时打包 Android 和 iOS，非常适合跨平台项目。

打包 Android APK

  1. 打开终端，进入 Flutter 项目根目录
  2. 执行命令：flutter build apk --release
  3. 打包完成后，APK 会生成在：<项目目录>/build/app/outputs/flutter-apk/app-release.apk

4.1.2 打包 iOS IPA

  1. 进入 Flutter 项目根目录
  2. 执行命令：flutter build ios --release
  3. 生成的 Xcode 工程会在：<项目目录>/ios/Runner.xcarchive
  4. 可以用 Xcode 导出 IPA 文件，用于真机安装或发布到 App Store

3.2 原生打包

Android 原生打包

如果需要自定义 Android 构建流程或处理原生插件，可以使用 Gradle 打包。

  1. 进入 Android 根目录：cd android

  2. 执行命令：

    ./gradlew clean # 清理旧的构建缓存./gradlew assembleDebug # 打包 debug 版本./gradlew assembleRelease# 打包 release 版本

  3. 生成的 APK 在：<项目目录>/android/app/build/outputs/apk/

iOS 原生打包

如果只针对 iOS 或需要自定义构建流程，可以直接用 Xcode 打包。

  1. 打开 Flutter 项目的 iOS 文件夹：<项目目录>/ios/Runner.xcworkspace
  2. 在 Xcode 中选择 Runner → Target → Signing & Capabilities 配置开发者账号
  3. 选择 Product → Archive 打包
  4. 通过 Organizer 导出 IPA 文件，可安装到真机或上传 App Store

注意：在 Mac 或 Linux 上，如果 ./gradlew 提示 Permission Denied，先执行：chmod +x gradlew。

3.3 安装到设备

打包完成后，可以直接安装到设备或模拟器测试：

  • Android：adb install app-release.apk
  • iOS：使用 Xcode 或 Apple Configurator 2 将 IPA 文件安装到真机；也可以通过 TestFlight 测试。

4 常见问题和解决方案

如何运行 Gradle 任务？

  • 使用 Gradle Wrapper：在终端中进入到 Flutter 项目目录，然后运行 ./gradlew <task_name> 命令来执行任务。
  • 使用本地安装的 Gradle ：在本地安装 Gradle，并将其添加到系统路径中，运行 gradle <task_name> 命令来执行任务。

其中 <task_name> 是你要运行的 Gradle 任务的名称，比如 assembleDebug。这将使用 Gradle Wrapper 来运行指定的任务。在 Flutter 项目中，通常会使用 Gradle Wrapper 来管理 Gradle 版本和构建项目。

Gradle Wrapper 相关命令

  • ./gradlew build：构建项目，编译项目的源代码并生成可执行文件。

  • ./gradlew clean：清理项目，删除构建过程中生成的临时文件和输出文件。

  • ./gradlew tasks：列出项目中可用的所有任务，包括构建任务、测试任务等。

  • ./gradlew assemble：将项目的构建结果打包成可分发的格式，例如 JAR、APK 等。

  • ./gradlew test：运行项目中的测试。

  • ./gradlew dependencies：显示项目的依赖关系。

  • ./gradlew help：获取关于 Gradle Wrapper 的帮助信息。

如何查看 Flutter 相关设置？

项目中搜不到 flutter.compileSdkVersion  相关信息，可打开文件 /flutter/packages/flutter_tools/gradle/src/main/groovy/flutter.groovy，此文件配置 flutter 设置，或者在 build.gradle 文件中直接修改。

iOS 真机调试失败

iOS14 之后，debug 模式下 Flutter 应用必须从 Flutter 工具链启动。如果报错，可以直接用 release 模式运行。

flutter run --release

如果提示缺少 pbxproj 模块，就用 Python 装一下：

pip3 install pbxproj

Gradle 报错 ZipException: zip END header not found

Launching lib/main.dart on sdk gphone64 arm64 in debug mode...Running Gradle task 'assembleDebug'...Exception in thread "main" java.util.zip.ZipException: zip END header not found at java.base/java.util.zip.ZipFileSource.findEND(UnknownSource)atjava.base/java.util.zip.ZipFileSource.findEND(Unknown Source) at java.base/java.util.zip.ZipFileSource.initCEN(Unknown Source) at java.base/java.util.zip.ZipFileSource.<init>(UnknownSource)atjava.base/java.util.zip.ZipFileSource.<init>(Unknown Source) at java.base/java.util.zip.ZipFileSource.get(Unknown Source) at java.base/java.util.zip.ZipFileCleanableResource.<init>(UnknownSource)atjava.base/java.util.zip.ZipFile.<init>(UnknownSource)atjava.base/java.util.zip.ZipFile.<init>(UnknownSource)atjava.base/java.util.zip.ZipFile.<init>(UnknownSource)atorg.gradle.wrapper.Install.unzip(Install.java:214)atorg.gradle.wrapper.Install.accessCleanableResource.<init>(Unknown Source) at java.base/java.util.zip.ZipFile.<init>(Unknown Source) at java.base/java.util.zip.ZipFile.<init>(Unknown Source) at java.base/java.util.zip.ZipFile.<init>(Unknown Source) at org.gradle.wrapper.Install.unzip(Install.java:214) at org.gradle.wrapper.Install.access600(Install.java:27) at org.gradle.wrapper.Install1.call(Install.java:74)atorg.gradle.wrapper.Install1.call(Install.java:74) at org.gradle.wrapper.Install1.call(Install.java:48) at org.gradle.wrapper.ExclusiveFileAccessManager.access(ExclusiveFileAccessManager.java:65) at org.gradle.wrapper.Install.createDist(Install.java:48) at org.gradle.wrapper.WrapperExecutor.execute(WrapperExecutor.java:128) at org.gradle.wrapper.GradleWrapperMain.main(GradleWrapperMain.java:61)Error: Gradle task assembleDebug failed with exit code 1

这个错误信息表明在运行 Gradle 任务 'assembleDebug' 时出现了问题，具体是由于 Java 在解压缩时找不到 zip 文件的 END 头部导致的。这可能是由于 Gradle Wrapper 下载的 Gradle 压缩包文件损坏或不完整导致的。

  • Gradle Wrapper 是 Gradle 官方提供的一个工具，用于帮助项目在没有预先安装 Gradle 的情况下运行。当你使用 Gradle Wrapper 时，项目会包含一个名为 gradlew 或 gradlew.bat 的脚本文件，以及一个名为 gradle/wrapper 的文件夹，其中包含了 Gradle Wrapper 所需的配置文件和 Gradle 版本的压缩包。
  • Gradle Wrapper 的作用就是在项目中管理 Gradle 版本，它会自动下载和使用指定版本的 Gradle，无需手动安装 Gradle。
  • /Users/edy/.gradle/wrapper/dists/gradle-7.6.3-all 这个目录中存储的是 Gradle 的 Wrapper 文件。

解决步骤：

  1. 删除 Gradle 缓存：运行 flutter clean 命令清除 Flutter 项目的构建缓存。

  2. 删除 Gradle：删除 /Users/edy/.gradle/wrapper/dists/gradle-7.6.3-all Gradle 压缩包文件

  3. 重新运行 ./gradlew assembleDebug 任务，Gradle 会自动重新下载

avatar
文章
阅读
粉丝