Skip to content

6. 第 5 章 - 将 Flutter 应用移植到移动端、桌面端和 Web

6.1. 同一份源代码,多个编译目标

这是本章的核心,也是本课程这一版本存在的理由:第 4 章的所有代码([lib/]、[pubspec.yaml]、[assets/])一行都不用改,无论选择哪个目标平台。这里的“移植”只需选择不同的编译命令([flutter run -d <target>] 或 [flutter build <target>]),完全不必编写、复制或修改任何组件(Widget)。这与使用本课程其余部分所介绍的工具进行移植所需的工作截然不同:[Vue.js]/[React]/[Angular] 客户端只能在浏览器中原生运行,要将其移植到移动端,需要借助第三方工具([Cordova]/[Capacitor],本课程不使用),把它打包进一个原生外壳,而这个外壳实际上包含一个内嵌浏览器([WebView]):代码虽然不变,但它仍然不是原生可执行文件,这与 [Flutter] 在移动端和桌面端生成的结果不同(参见第 3 章“Flutter 不是什么”)。

六个目标平台([Android]、[iOS]、[macOS]、[Windows]、[Linux]、[web])在使用 [flutter create] 创建的任何项目中,自 [Flutter 3] 起(参见第 1 章)默认全部启用,项目端无需任何配置即可添加其中任何一个。各目标平台之间的差异仅在于:开发机上安装的原生编译工具([Xcode]、[Visual Studio]、[GTK]等),实际执行的命令,以及(仅限移动端)本章后面将介绍的一个网络配置细节。

6.2. Web 目标平台

第 2 章已经使用过的目标平台([flutter run -d chrome])。只需两条命令:

flutter run -d chrome              # development, with hot reload
flutter build web                  # production build, in build/web/

[flutter build web] 生成一个独立的 [build/web/] 文件夹(包含 [index.html]、编译后的 [JavaScript]或 [WebAssembly] 以及资源文件),可部署到任意静态 Web 服务器([Nginx]、[Apache],或简单的 [npx serve]等),这与 在 [Vue.js]/[Vite] 一侧由 [npm run build] 生成的 [dist/] 文件夹完全一样。该构建产物仍然是由浏览器提供服务的 [JavaScript] 文件,因此它依然依赖一个能从该浏览器访问到的 [NestJS] 服务器,也就依赖 [app.enableCors()](参见服务器端的 [src/main.ts] )——它已经处于启用状态,针对此目标平台无需在服务器端做任何修改。

此目标平台特有的一点需要注意:登录界面中的“服务器 URL”字段(参见 [_ServerUrlField] ,位于 [lib/app.dart],第 4 章)必须指向运行该应用的浏览器能够访问的地址——只要 [NestJS] 服务器与浏览器运行在同一台机器上,[http://localhost:8080] 就是可接受的。

6.3. 桌面目标平台

三种操作系统,对应三套原生前置工具(参见第 1 章),但 [flutter] 命令的形式完全相同:

1
2
3
4
5
6
7
flutter run -d macos               # macOS - requires Xcode
flutter run -d windows              # Windows - requires Visual Studio (C++ Desktop)
flutter run -d linux                # Linux - requires the GTK development packages

flutter build macos                 # production build
flutter build windows
flutter build linux

每条 [flutter build <target>] 命令都会生成一个独立的原生可执行文件([.app] (macOS)、[.exe] 及其库文件(Windows)、[ELF] 二进制文件(Linux)),位于 [build/<target>/]中——与 Web 构建产物不同,这种可执行文件不在任何浏览器或任何 [WebView] 中运行:这是直接在操作系统上运行的原生代码,拥有自己的窗口和标题栏,由 [Flutter] 自身管理。

此目标平台不需要任何特殊的网络配置:桌面应用与用户运行在同一台机器上,访问 [http://localhost:8080] 的方式与安装在该机器上的任何其他程序完全一样(与其他目标平台一样,如有必要,可通过登录界面的“服务器 URL”字段指向远程服务器)。

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

Run "flutter emulators" to list and start any available device emulators.

If you expected another device to be detected, please run "flutter doctor" to diagnose potential issues. You
may also try increasing the time to wait for connected devices with the "--device-timeout" flag. Visit
https://flutter.dev/setup/ for troubleshooting tips.
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d windows

得到如下结果:

Image

上面的屏幕不是来自浏览器,而是来自一个 Windows 应用。要使其正常工作,必须具备某些工具:

1
2
3
4
[√] Visual Studio - develop Windows apps (Visual Studio Build Tools 2026 18.9.0) [221ms]
    • 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

要清楚了解 Flutter 项目还缺少什么,请输入以下命令:

flutter doctor -v

6.4. 目标模拟器

该 Flutter 应用已在 Android 模拟器上测试过:

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

...
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d emulator-554

模拟器中的结果:

Image

  • 注意 [1] 中的 URL;

使用 admin / admin 登录,得到如下结果:

Image

填写表单,然后提交:

Image

上面是我们使用 Web 应用预约的时间段。

6.5. 移动目标平台

注意:审阅者尚未测试本节内容。

这是最需要留意的部分,原因是模拟器/仿真器的网络存在一个特有的细节。

1
2
3
4
5
6
7
8
9
flutter emulators                   # lists the configured Android emulators
flutter emulators --launch <id>     # starts an Android emulator
open -a Simulator                   # starts an iOS simulator (macOS only)

flutter run -d <emulator-or-device-id>

flutter build apk                   # Android build (.apk), or:
flutter build appbundle             # Android build for the Play Store (.aab)
flutter build ios                   # iOS build - requires macOS + Xcode + an Apple developer account for a physical device

6.5.1. 移动端特有的网络陷阱:localhost 不再指向开发用的 PC

这是此目标平台必须了解的关键细节,与 [Flutter] 本身无关:登录界面“服务器 URL”字段中的 [localhost] (或 [127.0.0.1])始终指向运行该代码的机器——而移动模拟器/仿真器是一台与开发机不同的虚拟机,服务器([NestJS])就运行在开发机上,即使两者看起来“在同一台计算机上”。

  • [Android] 模拟器(由 [Android Studio] 创建):使用 [http://10.0.2.2:8080]——这是官方 [Android] 模拟器特有的特殊地址,会自动重定向到宿主机(开发 PC)上的 [localhost] 。
  • [iOS] 仿真器(仅限 macOS):[http://localhost:8080] 可直接使用,因为 [iOS] 仿真器与宿主机共享网络(这与 [Android] 模拟器不同)。
  • 物理设备([Android] 或 [iOS],与开发 PC 连接到同一 Wi-Fi 网络):使用这台 PC 在该网络上的本地 [IP] 地址(例如 [http://192.168.1.42:8080]),绝不能使用 [localhost] 或 [10.0.2.2],因为在这种情况下两者都指向移动设备本身。

6.5.2. 移动设备特有的两项额外限制

  • [Android] (自 API 28 起)默认阻止所有明文 [HTTP] 流量(未使用 [https://] 加密)——由于本课程的 服务器 在简单模式下监听 [HTTP],一个可用于生产环境的 [Android] 应用应当声明显式的例外(在生成的 [Android] 清单中加入 [android:usesCleartextTraffic="true"] ,或采用更细粒度的网络安全配置)——这是位于 [android/] 中的原生配置项,不属于本文所介绍的 [Dart] 代码。
  • [iOS] 实施了类似的策略,即 [App Transport Security]([ATS]),它同样默认阻止明文 [HTTP] ——需要在 [ios/Runner/Info.plist] 中声明等效的例外([NSAppTransportSecurity]、[NSAllowsArbitraryLoads],或者更具体地,仅针对开发服务器域名的例外)。

这两项设置仅适用于使用未加密 [HTTP] 服务器的开发/演示场景,例如本课程中使用的服务器——真正的生产部署会让 [NestJS] 服务器本身以 [https://] 对外提供服务(例如放在 [reverse proxy] 如 [Nginx] 之后),这样就不再需要这两项例外。

6.5.3. 更窄的屏幕:布局陷阱

移动设备特有的最后一个差异与网络无关:竖屏状态下的手机宽度只有约 360 像素(以 [Flutter] 的逻辑像素计),而浏览器或桌面窗口则要宽出数百像素。因此,为大屏幕设计的界面在手机上可能变得无法使用:本文档客户端的第一个版本在 [Android] 模拟器上测试时就出现了这种情况。医生/日期/按钮选择器([doctor_day_picker.dart])把三个字段排在同一个 [Row] 中,而标题栏([app.dart])则一次性显示所有内容:必须把模拟器切换到横屏模式才能看到全部内容。第 4 章给出了修复方法。由此得出两条规则:

  • 永远不要假定宽度。选择布局时,应检查实际可用的宽度——既可以使用 [LayoutBuilder]([constraints.maxWidth])在组件树的特定位置检查,也可以使用 [MediaQuery.sizeOf(context).width]检查整个屏幕——然后选择 [Row] (宽屏)或 [Column] (窄屏)。
  • 尽早在窄屏上测试:使用竖屏模式的模拟器,或将 [Chrome] 窗口缩窄。在调试模式下,[Flutter] 会在应用中以黄黑相间的横幅显示“RIGHT OVERFLOWED BY … PIXELS”,并在控制台输出一条消息,提示内容过宽。

这与下面的观察并不矛盾:布局根据屏幕尺寸而调整,而绝不是根据平台——代码中不会出现 [if (kIsWeb)] 。缩窄浏览器或桌面窗口,会触发与手机完全相同的“窄屏”布局。

6.6. 汇总表

  • [web] — [flutter run -d chrome] / [flutter build web] — 编译为 [JavaScript]/[WebAssembly],由浏览器执行 — 服务器 URL:[localhost] (同一台机器)。
  • [desktop] (macOS/Windows/Linux)— [flutter run -d <os>] / [flutter build <os>] — 原生 [AOT] 编译,独立可执行文件 — 服务器 URL:[localhost] (同一台机器)。
  • [mobile](Android 模拟器)— [flutter run] — 原生 [AOT] 编译 — 服务器 URL:[10.0.2.2] (模拟器的特殊地址)。
  • [mobile] (iOS 仿真器)— [flutter run] — 原生 [AOT] 编译 — 服务器 URL:[localhost] (与宿主机共享网络)。
  • [mobile] (物理设备)— [flutter run] — 原生 [AOT] 编译 — 服务器 URL:开发 PC 的本地 [IP] 地址,另加 [cleartext]/[ATS] 例外。

6.7. Dart 代码中不变的部分

最后需要强调的是,为了覆盖这三类目标平台,有哪些东西根本不需要编写或修改:第 4 章中没有出现任何 [if (kIsWeb) { ... } else { ... }] 条件,没有单独的 [_mobile.dart]/[_web.dart] 文件,也没有额外的抽象库。第 4 章中已经做出的少数几个选择,本身就足以让这段代码可在三类目标平台之间移植:使用 [shared_preferences] (而不是 [localStorage],后者仅限浏览器)实现持久化,使用 [rootBundle.loadString(...)](而不是向 Web 服务器发起 [fetch] 请求)加载内嵌的翻译字典,并使用 [http] 包(而不是浏览器专用的 API)进行网络通信。这正是本文档引言所承诺的:[a single Flutter codebase is enough to build a mobile app, a desktop app and a web app]。