2. 第 1 章 - 搭建工作环境
2.1. 安装工具
- Node.js:从 nodejs.org下载并安装 22 版(或更高版本)。在终端中验证安装:
- Visual Studio Code (VSCode):可从 code.visualstudio.com免费下载。安装“TypeScript and JavaScript Language Features”扩展(通常已内置)。
- [MySQL] 8:例如通过 XAMPP、Laragon(在 Windows 上)安装,或直接通过 [MySQL] Community Server安装。图形化管理工具(phpMyAdmin、[MySQL] Workbench、DBeaver、HeidiSQL……)可以简化操作。后文使用的是 Laragon 工具。
- Postman:可从 postman.com免费下载。
2.1.1. 安装 Flutter 客户端
不选择任何项目,启动 VSCode:

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

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

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

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

- 在 [6] 中,输入项目名称。它同时也是为项目创建的文件夹的名称;

- 在 [1-3] 中,指定项目的目标平台:[1 – Android 应用,2 – 桌面应用,3 – Web 应用];

- 在 [4] 中,是已创建的项目。VSCode 会自动下载 Flutter SDK;
如果您已下载本文档的代码,它位于两个文件夹中:


- 在 [1] 中,是 [Flutter]客户端;
- 在 [2] 中,是 [NestJS]服务器;
- 在 [3] 中,是 [2] 的内容。将所有这些内容复制到您的 Flutter 项目文件夹中。项目中会出现新的元素:

命令 [flutter doctor] 会逐个目标平台地检查 [Flutter] 所需的一切是否就绪。请在 Flutter 项目内的终端中运行它:
一切正常时,您将得到类似下面的结果(版本号可能不同):
每一行都以一个符号开头:[√] (一切正常)、[!] (警告:缺少某个元素,但不一定妨碍代码运行)或 [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 应用需要通信的 Web 服务尚未启动,您现在也可以启动该应用。首先,列出 Flutter 识别到的应用(设备):
在第 2 列中,您会看到所识别设备的 ID。要在其中某个设备上启动 Flutter 应用:
例如,要在标识符为 (chrome) 的 Chrome 浏览器中启动应用:
这将产生以下结果(或服务器连接错误):

您可能尚未安装 Flutter 所需的 Android SDK。下面我们来介绍如何安装它。
2.1.2. 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)]。当 [flutter doctor] 显示“cmdline-tools component is missing”时,缺少的正是 [Android SDK Command-line Tools] 软件包。
- 接受 [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.1.3. 创建 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]上启动模拟器,或在终端中启动(第一条命令列出模拟器及其 ID):

- 等待 [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]检查 [PATH]中是否存在其他版本不同的 [adb]:两个版本的 [adb] 争用连接会导致此问题。
一旦模拟器被识别,就可以用下面的命令在其上启动应用。注意:在模拟器中,[localhost] 指的是模拟器本身而不是计算机;“Server URL”字段必须包含 [http://10.0.2.2:8080] (见第 5 章)。

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