Skip to content

2. 第 1 章 - 搭建工作环境

2.1. 安装工具

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

2.1.1. 安装 Flutter 客户端

不选择任何项目,启动 VSCode:

Image

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

Image

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

Image

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

Image

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

Image

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

Image

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

Image

  • 在 [4] 中,是已创建的项目。VSCode 会自动下载 Flutter SDK;

如果您已下载本文档的代码,它位于两个文件夹中:

Image

Image

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

Image

命令 [flutter doctor] 会逐个目标平台地检查 [Flutter] 所需的一切是否就绪。请在 Flutter 项目内的终端中运行它:

flutter doctor

一切正常时,您将得到类似下面的结果(版本号可能不同):

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\flutter_application_1> flutter doctor
Doctor summary (to see all details, run flutter doctor -v):
[√] Flutter (Channel stable, 3.44.9, on Microsoft Windows [version 10.0.26200.9457], locale fr-FR)
[√] Windows Version (Windows 11 or higher, 25H2, 2009)
[√] Android toolchain - develop for Android devices (Android SDK version 37.0.0)
[√] Chrome - develop for the web
[√] Visual Studio - develop Windows apps (Visual Studio Build Tools 2026 18.9.0)
[√] Connected device (3 available)
[√] Network resources

• No issues found!

每一行都以一个符号开头:[√] (一切正常)、[!] (警告:缺少某个元素,但不一定妨碍代码运行)或 [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]命令会提供每项检查的详细信息。

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\flutter_application_1> flutter doctor -v
[√] Flutter (Channel stable, 3.44.9, on Microsoft Windows [version 10.0.26200.9457], locale fr-FR) [305ms]
    • Flutter version 3.44.9 on channel stable at C:\Users\serge\flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 6b182d2c75 (7 weeks ago), 2026-08-05 10:04:07 -0700
    • Engine revision 5a2a6a42cc
    • Dart version 3.12.2
    • DevTools version 2.57.0
    • Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop,
      enable-android, enable-ios, cli-animations, enable-native-assets, enable-swift-package-manager,
      omit-legacy-version-file, enable-lldb-debugging, enable-uiscene-migration

[√] Windows Version (Windows 11 or higher, 25H2, 2009) [895ms]

[√] Android toolchain - develop for Android devices (Android SDK version 37.0.0) [1 793ms]
    • Android SDK at C:\Users\serge\AppData\Local\Android\sdk
    • Emulator version 37.1.11.0 (build_id 15917651) (CL:N/A)
    • Platform android-37.0, build-tools 37.0.0
    • Java binary at: C:\Program Files\Android\Android Studio\jbr\bin\java
      This is the JDK bundled with the latest Android Studio installation on this machine.
      To manually set the JDK path, use: `flutter config --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment (build 25.0.3+-15898627-b508.16)
    • All Android licenses accepted.

[√] Chrome - develop for the web [114ms]
    • Chrome at C:\Program Files\Google\Chrome\Application\chrome.exe

[√] Visual Studio - develop Windows apps (Visual Studio Build Tools 2026 18.9.0) [113ms]
    • Visual Studio at C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools
    • Visual Studio Build Tools 2026 version 18.9.12105.275
    • Windows 10 SDK version 10.0.26100.0

[√] Connected device (3 available) [216ms]
    • Windows (desktop) • windows • windows-x64    • Microsoft Windows [version 10.0.26200.9457]
    • Chrome (web)      • chrome  • web-javascript • Google Chrome 151.0.7922.174
    • Edge (web)        • edge    • web-javascript • Microsoft Edge 153.0.4234.48

[√] Network resources [274ms]
    • All expected network resources are available.

• No issues found!

即使 Flutter 应用需要通信的 Web 服务尚未启动,您现在也可以启动该应用。首先,列出 Flutter 识别到的应用(设备):

1
2
3
4
5
6
7
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices                 
Found 4 connected devices:
sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
10.0.26200.9457]
Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

在第 2 列中,您会看到所识别设备的 ID。要在其中某个设备上启动 Flutter 应用:

flutter run -d <device_id>

例如,要在标识符为 (chrome) 的 Chrome 浏览器中启动应用:

flutter run -d chrome

这将产生以下结果(或服务器连接错误):

Image

您可能尚未安装 Flutter 所需的 Android SDK。下面我们来介绍如何安装它。

2.1.2. Android Studio 和 Android 命令行工具

本课程的移动端目标平台是 [Android]手机。要编译应用并将其安装到这部手机上,[Flutter] 需要 [Android] SDK,它随 [Android Studio](Google 的开发环境)一同安装。[Android Studio] 不用于编写代码——编辑器仍然是 [VSCode]——在这里它仅用于安装和更新 [Android] SDK。

  1. [Android Studio]:从 [https://developer.android.com/studio] 免费下载并安装。首次启动时,向导会提供标准安装:接受它,它就会下载 [Android] SDK。

Image

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

Image

  1. [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] 软件包。
  2. 接受 [Android] SDK 的许可协议 :在 Flutter 项目内的终端中输入以下命令,然后对每个问题回答 “[y]” ,直到看到消息“All SDK package licenses accepted.”:
    flutter doctor --android-licenses
    

[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]中勾选了它,见上文),但不提供现成可用的虚拟设备:您必须自己创建一个。

  1. [Prerequisite]:必须在计算机的 [BIOS]中启用虚拟化,并且在 [Windows]下,必须勾选 [Windows Hypervisor Platform]功能([Control Panel / Programs / Turn Windows features on or off]),这需要重新启动。否则,模拟器将无法启动,或运行得非常缓慢。
  2. 从 [Device Manager] 打开 [Android Studio]:在主屏幕上选择 [More Actions / Virtual Device Manager] ,或在项目打开时选择 [Tools / Device Manager] (视版本而定:[View / Tool Windows / Device Manager])。

Image

  1. 点击 [Create Device],选择一个模板(例如 [Pixel 8]),然后点击 [Next]。为 [Android]处理器选择较新的 [x86_64]系统映像,并通过其旁边的 [Download]链接下载,然后点击 [Next] 和 [Finish]。

Image

Image

Image

  1. 使用 [Play]按钮在 [Device Manager]上启动模拟器,或在终端中启动(第一条命令列出模拟器及其 ID):
    flutter emulators
    flutter emulators --launch <id>
    

Image

  1. 等待 [Android]欢迎界面出现在模拟器窗口中:首次启动可能需要几分钟。然后确认 [Flutter] 识别到了该模拟器,它应出现在列表中(例如 [emulator-5554],平台为 [android-x64]):
flutter devices
1
2
3
4
5
6
7
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices
Found 4 connected devices:
  sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
  Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
  10.0.26200.9457]
  Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
  Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

[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] 。

1
2
3
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" kill-server
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" start-server
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" devices

如果问题依然存在,请使用 [where.exe adb]检查 [PATH]中是否存在其他版本不同的 [adb]:两个版本的 [adb] 争用连接会导致此问题。

一旦模拟器被识别,就可以用下面的命令在其上启动应用。注意:在模拟器中,[localhost] 指的是模拟器本身而不是计算机;“Server URL”字段必须包含 [http://10.0.2.2:8080] (见第 5 章)。

flutter run -d emulator-5554

Image

2.1.4. 准备 Android 手机

要在真实的 [Android]手机上运行应用,必须将手机设置为允许由计算机控制:

  1. 启用开发者选项:打开 [Settings / About phone],然后多次点击 [Build number](通常为 7 次),直到手机提示您已成为开发者。具体的菜单名称因厂商而异。
  2. 在 [Developer options] 菜单(上一步中添加)中启用 [USB debugging] 。
  3. 使用支持数据传输(而不仅仅是为手机充电)的 USB 线将手机连接到计算机,并在手机上接受 USB 调试授权请求。在 Windows 上,如果手机未被识别,请安装厂商的 USB 驱动程序(“OEM USB drivers”,见 [https://developer.android.com/studio/run/oem-usb])。
  4. 确认 [Flutter] 检测到了手机:它应出现在下面命令显示的列表中,平台为 [android]:
    flutter devices
    

手机将通过计算机在本地网络中的 IP 地址(而不是 [localhost])访问 [NestJS]服务器:这一配置将在第 5 章中说明。