登录 / 注册
banner
约 2,400 字
8 分钟

Flutter 开发环境安装：从 SDK 到 Android 真机调试

摘要

一份面向 Linux 用户的 Flutter 开发环境安装笔记，覆盖 Flutter SDK、VS Code、Android SDK 命令行工具、JDK、真机调试和常见构建问题处理。

Flutter 是 Google 推出的跨平台应用开发框架，可以用一套 Dart 代码开发 Android、iOS、Linux、Windows、macOS 和 Web 应用。对刚开始学习 Flutter 的用户来说，真正容易卡住的地方往往不是 Dart 语法，而是开发环境：Flutter SDK、Android SDK、Java、VS Code 插件、真机调试，这几部分需要配合好。

这篇文章整理一套比较通用的 Flutter 安装流程，重点适合 Linux 用户，尤其是想用 VS Code 写 Flutter、用 Android 真机调试，而不是一开始就安装完整 Android Studio 的情况。

准备 Flutter SDK

Flutter SDK 是整个 Flutter 开发环境的核心。它包含 Flutter 命令行工具、Dart SDK、项目模板、构建工具和调试工具。

建议把 Flutter SDK 放在用户目录下，不要放进 /usr、/opt 这类需要管理员权限的位置。这样后续升级和管理会更方便。

可以先创建一个开发目录：

bash
mkdir -p ~/dev
cd ~/dev

然后从官方仓库克隆 stable 分支：

bash
git clone https://github.com/flutter/flutter.git -b stable

此时 Flutter SDK 路径大概是：

纯文本
~/dev/flutter

接着把 Flutter 加入 PATH。如果使用 bash，可以写入 ~/.bashrc：

bash
echo 'export PATH="$HOME/dev/flutter/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

如果使用 fish，可以执行：

fish
fish_add_path -U $HOME/dev/flutter/bin

检查是否安装成功：

bash
which flutter
flutter --version
flutter doctor

如果 which flutter 能输出类似下面的路径，就说明 Flutter 命令已经可以被系统找到：

纯文本
/home/你的用户名/dev/flutter/bin/flutter

安装 VS Code 插件

Flutter 可以使用 Android Studio、IntelliJ IDEA，也可以使用 VS Code。对于轻量开发来说，VS Code 足够好用。

在 VS Code 扩展商店中安装：

纯文本
Flutter
Dart

通常安装 Flutter 插件时，Dart 插件会一起安装。

如果 VS Code 提示：

纯文本
Could not find a Flutter SDK

说明它没有找到 Flutter SDK。此时点击 Locate SDK，选择 Flutter SDK 的根目录，例如：

纯文本
/home/你的用户名/dev/flutter

注意不要选择：

纯文本
/home/你的用户名/dev/flutter/bin

也不要选择 Flutter 项目目录。VS Code 要找的是 Flutter SDK 根目录。

如果图形界面选择后仍然识别失败，可以直接在 VS Code 设置里指定路径。打开命令面板：

纯文本
Ctrl + Shift + P

搜索：

纯文本
Preferences: Open User Settings (JSON)

加入：

JSON
{
  "dart.flutterSdkPath": "/home/你的用户名/dev/flutter"
}

如果原来已经有其他设置，只需要在原来的 JSON 对象里增加这一项即可。

安装 Android SDK

如果只是开发 Flutter 桌面应用或 Web 应用，不一定马上需要 Android SDK。但如果要运行到 Android 手机、打 APK 或使用模拟器，就必须安装 Android SDK。

Android SDK 有两种常见安装方式。

第一种是安装完整 Android Studio。它带有图形化的 SDK Manager、Device Manager 和模拟器管理工具，适合不想手动配置的人。

第二种是只安装 Android SDK Command-line Tools。它更轻量，适合使用 VS Code 写代码、用命令行管理 SDK、用真机调试的用户。

如果选择命令行工具方式，可以先创建 SDK 目录：

bash
mkdir -p ~/Android/Sdk/cmdline-tools/latest

然后到 Android Studio 官网下载页面，找到 Command line tools only，下载 Linux 版命令行工具压缩包。

解压后，需要把内容放到：

纯文本
~/Android/Sdk/cmdline-tools/latest

正确目录结构应该类似：

纯文本
~/Android/Sdk/cmdline-tools/latest/
├── bin/
├── lib/
├── NOTICE.txt
└── source.properties

然后配置 Android SDK 环境变量。

bash 用户可以写入 ~/.bashrc：

bash
echo 'export ANDROID_HOME="$HOME/Android/Sdk"' >> ~/.bashrc
echo 'export ANDROID_SDK_ROOT="$HOME/Android/Sdk"' >> ~/.bashrc
echo 'export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"' >> ~/.bashrc
source ~/.bashrc

fish 用户可以执行：

fish
set -Ux ANDROID_HOME $HOME/Android/Sdk
set -Ux ANDROID_SDK_ROOT $HOME/Android/Sdk

fish_add_path -U $ANDROID_HOME/cmdline-tools/latest/bin
fish_add_path -U $ANDROID_HOME/platform-tools
fish_add_path -U $ANDROID_HOME/emulator

检查 sdkmanager 是否可用：

bash
sdkmanager --version

然后安装 Android 开发所需组件：

bash
sdkmanager --sdk_root="$ANDROID_HOME" --install \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0"

如果还需要模拟器，可以继续安装：

bash
sdkmanager --sdk_root="$ANDROID_HOME" --install \
  "emulator" \
  "system-images;android-36;google_apis;x86_64"

接受 Android SDK 许可证：

bash
sdkmanager --sdk_root="$ANDROID_HOME" --licenses
flutter doctor --android-licenses

安装 Java JDK

Android 构建需要 Java。这里要注意：需要的是 JDK，而不只是 JRE。JDK 里包含 javac 编译器，而 JRE 只负责运行 Java 程序。

可以先检查：

bash
java --version
javac --version

如果 java 有输出，但 javac 找不到，说明只安装了运行环境，没有安装开发环境。

Android Gradle Plugin 对 Java 版本比较敏感。通常推荐使用 JDK 17，这是目前 Android 构建链里兼容性最稳的选择之一。过新的 Java 版本可能会出现 Gradle toolchain 识别问题，例如：

纯文本
Toolchain installation ... does not provide the required capabilities: [JAVA_COMPILER]

Linux 发行版仓库里如果能直接安装 JDK 17，可以优先使用系统包管理器。例如 Fedora 系可以先搜索：

bash
dnf search openjdk-devel

如果系统仓库没有合适的 JDK 17，也可以安装 Temurin JDK 17。

添加 Adoptium 仓库：

bash
sudo tee /etc/yum.repos.d/adoptium.repo >/dev/null <<'EOF'
[Adoptium]
name=Adoptium
baseurl=https://packages.adoptium.net/artifactory/rpm/fedora/$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://packages.adoptium.net/artifactory/api/gpg/key/public
EOF

安装 JDK 17：

bash
sudo dnf install -y temurin-17-jdk

安装后查看 JDK 路径：

bash
ls -d /usr/lib/jvm/*17*

假设路径是：

纯文本
/usr/lib/jvm/temurin-17-jdk

bash 用户可以写入：

bash
echo 'export JAVA_HOME="/usr/lib/jvm/temurin-17-jdk"' >> ~/.bashrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

fish 用户可以执行：

fish
set -Ux JAVA_HOME /usr/lib/jvm/temurin-17-jdk
fish_add_path -U $JAVA_HOME/bin

检查：

bash
echo $JAVA_HOME
$JAVA_HOME/bin/java --version
$JAVA_HOME/bin/javac --version

创建 Flutter 项目

环境基本准备好后，可以创建一个 Flutter 项目：

bash
cd ~/dev
flutter create my_app
cd my_app

也可以指定组织名。组织名会影响 Android 包名，例如：

bash
flutter create --org com.example my_app

项目结构大概如下：

纯文本
my_app/
├── lib/
│   └── main.dart
├── android/
├── linux/
├── pubspec.yaml
└── test/

其中最常写代码的位置是：

纯文本
lib/main.dart

android/ 目录是 Android 平台配置，通常在修改应用名、包名、权限、签名、Gradle 配置时才需要动。

pubspec.yaml 用来管理依赖、资源、字体和版本号。

运行到 Android 真机

先在手机上打开：

纯文本
开发者选项 → USB 调试

然后用数据线连接电脑，执行：

bash
adb devices

手机上会弹出 USB 调试授权提示，选择允许。

再检查 Flutter 是否识别到设备：

bash
flutter devices

运行项目：

bash
flutter run --debug

如果有多个设备，可以指定设备 ID：

bash
flutter devices
flutter run --debug -d 设备ID

如果只是想先确认 Flutter 项目能跑，也可以先运行到 Linux 桌面端：

bash
flutter config --enable-linux-desktop
flutter run -d linux

在 Fedora 上，Linux 桌面运行可能还需要安装桌面构建依赖：

bash
sudo dnf install -y clang cmake ninja-build pkgconf-pkg-config gtk3-devel

在 VS Code 中运行

打开项目目录：

bash
cd ~/dev/my_app
code .

在 VS Code 中，主要编辑：

纯文本
lib/main.dart

按 F5 可以启动调试，也可以使用菜单：

纯文本
Run → Start Debugging

如果 VS Code 默认进入了 profile 或 release 模式，可以手动创建：

纯文本
.vscode/launch.json

写入：

JSON
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flutter Debug",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart",
      "flutterMode": "debug"
    },
    {
      "name": "Flutter Profile",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart",
      "flutterMode": "profile"
    },
    {
      "name": "Flutter Release",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart",
      "flutterMode": "release"
    }
  ]
}

然后在左侧 Run and Debug 面板中选择 Flutter Debug，再点击运行。

常见问题处理

如果 VS Code 找不到 Flutter SDK，需要确认 Flutter SDK 路径是否正确。它应该指向 Flutter 根目录，而不是 bin 目录，也不是项目目录。

错误示例：

纯文本
~/dev/flutter/bin
~/dev/my_app

正确示例：

纯文本
~/dev/flutter

如果 sdkmanager 报错说 JAVA_HOME 无效，说明环境变量还指向一个不存在的 Java 目录。需要重新设置：

bash
echo $JAVA_HOME

然后把 JAVA_HOME 改成实际存在的 JDK 目录。

如果 Android 构建时报：

纯文本
Toolchain installation ... does not provide the required capabilities: [JAVA_COMPILER]

通常说明 Gradle 没有拿到完整 JDK，或者拿到的是不兼容的 Java 版本。先确认：

bash
javac --version
echo $JAVA_HOME

必要时在项目的 android/gradle.properties 中固定 JDK 路径：

properties
org.gradle.java.home=/usr/lib/jvm/temurin-17-jdk

路径要根据自己机器上的实际 JDK 17 路径修改。

修改后停掉 Gradle 后台进程：

bash
cd android
./gradlew --stop
cd ..

然后重新构建：

bash
flutter clean
flutter pub get
flutter run --debug

如果命令行工具重复安装，出现类似：

纯文本
cmdline-tools/latest already exists
Installing in latest-2 instead

可以保留 latest，删除多出来的目录：

bash
rm -rf ~/Android/Sdk/cmdline-tools/latest-2

检查整体环境

安装完成后，可以用下面几条命令检查状态：

bash
flutter doctor -v
java --version
javac --version
echo $JAVA_HOME
sdkmanager --version
adb devices
flutter devices

一个比较稳妥的 Flutter Android 开发环境应该包含：

纯文本
Flutter SDK
Android SDK
Android SDK Platform-Tools
Android SDK Build-Tools
JDK 17
VS Code Flutter 插件
一台开启 USB 调试的 Android 手机

安装 Flutter 本身并不复杂，真正容易出问题的是路径和版本配合。只要确认 Flutter SDK、Android SDK 和 JDK 都能被命令行正确找到，再用 flutter doctor 检查剩余问题，基本就能把开发环境跑起来。

END

相关文章

把常用命令收进一个 TUI：cmdp 让终端工作流更顺手

-5 分钟

Linux 下刻录 DVD 数据盘：一套更稳的备份流程

-6 分钟

我为什么推荐 Vimium C：让浏览器真正进入“全键盘操作”

-4 分钟

Flatpak 微信获得了 Home 权限，却无法访问下载目录

-7 分钟
- / RSS / Sitemap
Powered by Tanstack Start & Flare Stack Blog