2. 搭建工作环境
2.1. 安装工具
-
Node.js:从 nodejs.org 下载并安装 22 版(或更高版本)。在终端中验证安装:
-
Visual Studio Code (VSCode):可从 code.visualstudio.com 免费下载。安装 [Flutter] 扩展(它同时会安装 [Dart] 扩展)。
-
[MySQL] 8:例如通过 XAMPP、Laragon(在 Windows 上)安装,或直接通过 [MySQL] Community Server安装。使用图形化管理工具(phpMyAdmin、[MySQL] Workbench、DBeaver、HeidiSQL……)会更简便。后面使用的是 Laragon 工具。
2.2. 安装 Flutter 客户端
不指定项目启动 VSCode:

- 在 [1-2] 中,打开命令面板;

- 在 [3] 中,创建新的 Flutter 项目;

- 在 [4] 中,创建一个应用;

- 在 [5-6] 中,指定将创建项目子文件夹的文件夹;

- 在 [6] 中,为项目命名。该名称也将是为项目创建的文件夹的名称;

- 在 [1-3] 中,指定项目目标,即 [1 – Android application, 2 – desktop application, 3 – web application];

- 在 [4] 中,是创建好的项目。VSCode 会自动下载 Flutter SDK;
命令 [flutter doctor] 会逐个目标检查 [Flutter] 所需的一切是否就绪。请在新创建的 Flutter 项目的 VSCode 终端中运行它:
一切正常时,你会得到如下结果(版本号可能不同):
每一行以一个符号开头:[√] (一切正常)、[!] (警告:缺少某个元素,但不一定妨碍代码运行)或 [X] (错误)。对本课程而言,相关的行是 [Flutter]、[Android toolchain] (为手机编译)、[Android]以及 [Connected device] (至少检测到一台设备,具体指手机)。[Chrome] (Web 目标)和 [Visual Studio] (Windows 目标)这两行只适用于相应的目标:[!] 或 [X] 出现在你不使用的目标上时可以忽略。
如果 [Android toolchain] 报告“cmdline-tools component is missing”,请安装 [Android SDK Command-line Tools] (见下文);如果它报告“Android license status unknown”,请接受许可(第 5 步)。[flutter doctor -v] 命令会提供每项检查的详细信息。
现在列出 Flutter 识别到的应用(设备):
在第 2 列中,你会找到所识别设备的 ID。要在其中某个设备上启动 Flutter 应用:
例如,要在 Edge 浏览器中启动 [flutter_application_1] 应用:
Edge 浏览器中会出现如下结果:

接下来我们将介绍如何安装 Android 开发所需的工具。
2.3. Android Studio 和 Android 命令行工具
本课程的目标设备是 [Android] 手机。要编译应用并将其安装到这部手机上,[Flutter] 需要 [Android] SDK,它们会随 [Android Studio](Google 的开发环境)一起安装。[Android Studio] 并不用于编写代码——编辑器仍然是 [VSCode]——在这里它只用于安装和更新 [Android] SDK。
- [Android Studio]:从 [https://developer.android.com/studio] 免费下载并安装。首次启动时,向导会提供标准安装:接受它,它就会下载 [Android] SDK。

- 打开 [SDK Manager] ,它位于 [Android Studio] 中(打开项目时通过 [Tools / SDK Manager] 菜单,或在主屏幕上通过 [More Actions / SDK Manager] ):它是安装和更新 [Android] SDK 组件的工具。
- [SDK Platforms] 选项卡:确认已安装较新的 [Android] 平台([Flutter] 文档在撰写本文时指定的是 36 版)。

- [SDK Tools] 选项卡:勾选 [Android SDK Command-line Tools (latest)]、[Android SDK Build-Tools]和 [Android SDK Platform-Tools] (如果想在模拟器上测试,还要勾选 [Android Emulator] ),然后点击 [Apply]。此外,[Flutter] 的文档还推荐 [CMake] 和 [NDK (Side by side)]。当 [Android SDK Command-line Tools] 包 缺失时,[flutter doctor] 就会显示“cmdline-tools component is missing”。
- 接受 [Android] SDK 的许可 :在 Flutter 项目的终端中输入以下命令,然后对每个问题回答 “[y]” ,直到看到消息“All SDK package licenses accepted.”:
[Note]:对于 [Android SDK Command-line Tools] 23.0 版,上述命令可能立即结束,不提示任何内容,并显示“The --licenses option is no longer needed.”这是 [Flutter] 中的已知问题(github.com/flutter/flutter 上的 issue 191558 和 191487)。解决办法:在 [SDK Manager] 的 [SDK Tools] 选项卡中,勾选 [Show Package Details],将 [Android SDK Command-line Tools] 的 23.0 版替换为 22.0 版,点击 [Apply],然后重新运行该命令。
2.4. 设置 Android 模拟器
如果没有手机,可以在 [Android] 模拟器上测试应用:这是一部在计算机窗口中运行的虚拟手机。[Android Studio] 会安装 [Android Emulator] 程序(如果在 [SDK Manager] 中勾选了它,见上文),但不提供现成可用的虚拟设备:你必须自己创建一个。
- [Prerequisite]:必须在计算机的 [BIOS] 中启用虚拟化,并且在 [Windows] 下勾选 [Windows Hypervisor Platform] 功能([Control Panel / Programs / Turn Windows features on or off]),这需要重启。否则,模拟器将无法启动或运行非常缓慢。
- 打开 [Device Manager] ,位于 [Android Studio] 中:在主屏幕上选择 [More Actions / Virtual Device Manager] ,或在打开项目时选择 [Tools / Device Manager] (视版本而定:[View / Tool Windows / Device Manager])。

- 点击 [Create Device],选择一个模板(例如 [Pixel 8]),然后点击 [Next]。选择较新的 [Android] 系统镜像,适用于 [x86_64] 处理器,并使用旁边的 [Download] 链接下载它,然后点击 [Next] 和 [Finish]。



- 使用 [Play] 按钮启动模拟器,该按钮位于 [Device Manager]:

- 等待 [Android] 主屏幕出现在模拟器窗口中:首次启动可能需要几分钟。然后确认 [Flutter] 能识别该模拟器,它应出现在列表中(例如 [emulator-5554],平台 [android-x64]):
[Note]:如果 [flutter devices] 没有显示模拟器,而是显示消息“Device emulator-5554 is offline”,说明模拟器尚未完成启动,或者 [adb] (连接计算机与设备的工具,随 [Android SDK Platform-Tools] 一起安装)处于不一致的状态。请按顺序尝试以下做法:(1) 等待欢迎屏幕出现,然后重新运行该命令;(2) 使用以下三条命令重启 [adb] (在 [Windows] 中,在 [PowerShell] 内),最后一条命令应显示“device”而不是“offline”;(3) 在该设备的 [Device Manager] 菜单([⋮])中,选择 [Cold Boot Now],或者在万不得已时选择 [Wipe Data] 。
如果问题仍然存在,请使用 [where.exe adb] 确认没有其他版本不同的 [adb] 存在于 [PATH] 中:两个版本的 [adb] 争抢连接就会导致此问题。
模拟器被识别后,使用以下命令在其上启动应用(参见 “安装与运行” 一节):

准备 Android 手机
要在真实的 [Android] 手机上运行应用,必须将手机设置为允许计算机控制:
- 启用开发者选项:打开 [Settings / About phone],然后连续点击 [Build number] 数次(通常为 7 次),直到手机提示你已成为开发者。具体名称因厂商而异。
- 启用 [USB debugging] ,位于 [Developer options] 菜单中(上一步中已添加)。
- 使用能传输数据的 USB 线(而不仅仅是给手机充电)将手机连接到计算机,并在手机上接受 USB 调试授权请求。在 Windows 上,如果手机未被识别,请安装制造商的 USB 驱动程序(“OEM USB drivers”,见 [https://developer.android.com/studio/run/oem-usb])。
- 确认 [Flutter] 能检测到手机:它应出现在下面命令显示的列表中,并带有 [android] 平台:
手机将通过计算机在本地网络中的 IP 地址访问 [NestJS] 服务器(而不是通过 [localhost]):这一配置将在第 5 章中介绍。