2. 搭建开发环境
2.1. 安装工具
- Node.js:从 nodejs.org 下载并安装 24 版(LTS)。[Angular CLI] 22 要求 [Node.js] 22.22.3(或更新的 22 版本)、24.15 或更高版本,或 26 及以上版本:版本过旧将无法运行 [ng] 命令。安装程序同时会安装 [npm],即 [Node.js] 的包管理器。在终端中验证安装:
-
Visual Studio Code ([VS Code]):可在 code.visualstudio.com 免费下载。安装扩展 [Angular Language Service](在 [HTML] 模板中提供自动补全和验证)和 [Ionic] (在编辑器中提供 [Ionic] 和 [Capacitor] 的命令)。对 [TypeScript] 的支持已内置于 [VS Code] 中。
-
Chrome:用于开发应用的浏览器(google.com/chrome)。其开发者工具(F12)可以以手机尺寸显示应用,也可以调试安装在手机上的应用(见附录)。
-
MySQL 8 (或 MariaDB):仅 JSON 服务器需要。可以通过 Laragon(在 [Windows] 下)、XAMPP,或直接通过 MySQL Community Server 安装。图形化管理工具([HeidiSQL]、[phpMyAdmin]、[MySQL Workbench]、[DBeaver]……)会让后续操作更轻松。本课程使用 [Laragon]。
2.2. 安装 Ionic 客户端
使用 [Flutter] 时,你必须安装 SDK:框架、[Dart] 语言以及它们的工具,它们对所有项目是通用的。使用 [Ionic] 则无需安装 SDK:[Angular]、[Ionic]、[Capacitor]、[TypeScript] 编译器及其命令行工具([ng]、[cap])都只是普通的 [npm] 包,在每个项目的 [package.json] 文件中声明,并安装在其 [node_modules/] 文件夹中。因此每个项目都有自己的版本,两个项目可以使用不同版本的 [Angular] 而互不干扰。
因此,为某个项目安装 [Ionic] 客户端,就是安装它的包。在 [VS Code] 中,打开项目文件夹(File 菜单 / Open Folder,例如 [examples_ionic] 文件夹),然后打开控制台(Terminal 菜单 / New Terminal),输入:
该命令会下载 [package.json] 中描述的包(连同它们的依赖项——数百个包,总计数百兆字节),版本与 [package-lock.json] 中列出的完全一致。只有在添加包或更改版本时,才需要再次运行此命令。
随后,项目的工具通过 [npx] 启动,它会执行安装在项目内部的包的命令(如果没有 [npx],控制台会去搜索系统范围内安装的命令)。[npx ng version] 命令用于验证 [Angular] 的安装:
结果大致如下(这里是在 [Linux] 下;在 [Windows] 下,[Operating System] 一行显示 [win32 x64]):
[Requested Version] 列列出 [package.json] 所请求的版本;[Installed Version] 列列出 [npm] 实际安装的版本。[Ionic] 和 [Capacitor] 的版本不会出现在此表中,该表仅限于 [Angular] 的包;命令 [npm ls --depth=0] 会列出所有版本。命令 [npx cap doctor] 对于 [Capacitor] 来说,相当于 [flutter doctor]:
[Capacitor] 会将项目中已安装的版本与最新发布的版本进行比较。[@capacitor/ios] 包并未安装:本课程只关注 [Android] ([iOS] 应用要在 [Mac] 上使用 [Xcode] 构建)。一旦 [Android] 项目创建完成([npx cap add android],见示例 01),该命令还会检查这个项目。
剩下的就是在同一个控制台中运行应用:
然后在 [Chrome] 中打开地址 [http://localhost:8100] :你将看到 25 个示例的菜单(见示例 01)。与 [Flutter] 不同,这里无需选择设备:在浏览器中,应用由 [ng serve] 提供服务;在 [Android] 上,则由 [Capacitor] 构建并安装。
[@ionic/cli] 工具 (可选)。[Ionic] 团队还发布了一个命令行工具,需在系统范围内安装:
- 第 1 行:安装 [ionic] 命令;
- 第 2 行:通过询问几个问题,基于模板创建一个新的 [Ionic] + [Angular] + [Capacitor] 项目([blank]:空白页,[tabs]:选项卡,[sidemenu]:侧边菜单);
- 第 3 行:启动开发服务器(它自身会调用 [ng serve]);
- 第 4 行:构建应用,将其安装到设备上([Android]), 并在代码被修改时重新加载它([-l],“实时重载”);[--external] 使开发服务器监听电脑在局域网中的地址,手机可以访问该地址。
这只是为了方便:[ionic] 只是把命令 [ng] 和 [cap] 串联起来,并且它要求项目中有一个 [ionic.config.json] 文件(由 [ionic start] 创建,对于已有项目则由 [ionic init] 创建)。本课程的 项目没有这个文件:它们是用 [ng new] 创建的(见示例 01),我们直接使用属于项目一部分的 [ng] 和 [cap] 。这是看清实际发生了什么的最直接的方式,而且不依赖于电脑上安装的任何工具。
接下来我们介绍如何安装开发 [Android] 所需的工具。
2.3. Android Studio 和 Android 命令行工具
本课程的目标设备是 [Android] 手机。要构建 [Android] 应用并将其安装到这部手机上,[Capacitor] 需要 [Android] SDK,和 JDK([Java] 编译器,供 [Gradle] 构建工具使用),它们会随 [Android Studio] 一起安装,后者是 [Google] 的开发环境。[Android Studio] 并不用于编写代码(编辑器仍然是 [VS Code]):这里用它来安装和更新 [Android] SDK、创建模拟器,以及偶尔打开由 [Android] 创建的 [Capacitor] 项目([npx cap open android])。
-
[Android Studio]:从 developer.android.com/studio 免费下载并安装。首次启动时,向导会提供标准安装:接受它,它就会下载 [Android] SDK。
-
从 [Android Studio] 打开 [SDK Manager] (打开项目时使用 [Tools / SDK Manager] 菜单,或在主屏幕上使用 [More Actions / SDK Manager] ):它用于安装和更新 [Android] SDK 的组件。
-
[SDK Platforms] 选项卡:确认已安装较新的 [Android] 平台。[Capacitor] 8 针对 API 36([Android] 16)编译应用;
-
[SDK Tools] 选项卡:勾选 [Android SDK Build-Tools]、[Android SDK Platform-Tools] (其中包含 [adb],即把电脑连接到设备的工具)、[Android Emulator] (如果你想在模拟器上测试)和 [Android SDK Command-line Tools (latest)] (其中包含工具 [sdkmanager]),然后点击 [Apply]。
-
接受 [Android] SDK 的许可协议:每次安装组件时,[Android Studio] 都会自动接受它们。如果之后应用构建因为有未接受的许可协议而失败,请使用 [sdkmanager] 工具(来自 [Android SDK Command-line Tools] 包),对每个问题回答 [y] ,直到出现消息“All SDK package licenses accepted.”,以接受全部许可协议(在 [Windows] 下,在 [PowerShell] 中):
-
JDK:[Capacitor] 8 需要 JDK 21 或更高版本。无需另行安装:[Android Studio] 自带一个,即 [JBR] (“JetBrains Runtime”),位于其 [jbr] 子文件夹中。在 [Android Studio] 的较新版本中,它是 [Java] 25:这需要对由 [Android] 生成的 [Capacitor] 项目做一个小调整(升级到 [Gradle] 9.1),如示例 01 所示。
-
环境变量。[Capacitor] ([npx cap run android])本身会启动 [Gradle] 构建和工具 [adb];它需要知道 SDK 和 JDK 的位置。在 [Windows] 下,进入“设置 / 系统 / 系统信息 / 高级系统设置 / 环境变量”,创建两个用户变量:
-
[ANDROID_HOME]:[Android] SDK 所在的文件夹;默认是 [C:\Users\<name>\AppData\Local\Android\Sdk] ([SDK Manager] 在其窗口顶部的 [Android SDK Location] 中显示此路径);
- [JAVA_HOME]:[Android Studio] 的 JDK 所在的文件夹;默认是 [C:\Program Files\Android\Android Studio\jbr]。
还要把 [%ANDROID_HOME%\platform-tools] 文件夹添加到 [Path] 变量中,以便能在控制台中输入 [adb] 。如果 [Android Studio] 没有安装在默认位置,[npx cap open android] 命令还需要变量 [CAPACITOR_ANDROID_STUDIO_PATH]:即 [studio64.exe] 程序的路径。新变量只对在其创建之后打开的控制台可见;你必须重启 [VS Code]。在新的控制台中检查:
2.4. 设置 Android 模拟器
如果你没有手机,可以在 [Android] 模拟器上测试应用:这是一部在电脑窗口中运行的虚拟手机。[Android Studio] 会安装 [Android Emulator] 程序(如果在 [SDK Manager] 中勾选了它,见上文),但不会提供现成可用的虚拟设备:你必须自己创建一个。
- [Prerequisites]:必须在电脑的 [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] 欢迎界面出现在模拟器窗口中:首次启动可能需要几分钟。
接下来,验证电脑是否识别到了模拟器。有两个命令可以做到这一点:
- 第 1 行:[adb] 列出连接到电脑的设备,每行一个:它们的标识符(例如第一个模拟器的 [emulator-5554] ),后面是它们的状态,应为 [device];
- 第 2 行:在 [Capacitor] 项目的文件夹中 (例如 [examples_ionic]),[Capacitor] 列出它可以安装应用的设备:已连接并运行的设备,以及在 [Android Studio] 中创建的模拟器,即使它们处于关闭状态(它知道如何启动它们)。这相当于 [flutter devices]。
[Note]:如果 [adb devices] 显示模拟器的状态为 [offline],说明模拟器尚未完成启动,或者 [adb] 处于不一致的状态。请按顺序尝试以下做法:(1) 等待欢迎界面出现,然后重新运行该命令;(2) 使用下面三个命令重启 [adb] (在 [Windows] 下,在 [PowerShell] 中),最后一个命令应显示 [device] 而不是 [offline];(3) 在 [Device Manager] 中,从设备的 [Cold Boot Now] 菜单([⋮])中选择,万不得已时甚至可以选择 [Wipe Data] 。
如果问题仍然存在,请使用 [where.exe adb] 验证 [Path] 中是否存在其他不同版本的 [adb]:两个版本的 [adb] 争用连接就会导致这个问题。
一旦模拟器被识别,就可以使用下面的命令(位于项目文件夹中)让应用自行安装到其上并启动,该命令应在 [npx ng build] 和 [npx cap sync android] 之后执行(见示例 01);[--target] 通过 ID 标识设备;否则,该命令会提示你选择一个:
在模拟器上,运行它的电脑的地址是 [10.0.2.2]:应用将在这里查找 JSON 服务器(见示例 22)。
2.5. 准备 Android 手机
要在真实的 [Android] 手机上运行应用,必须将手机设置为可由电脑控制:
- 启用开发者选项:打开 [Settings / About phone],然后多次(通常为 7 次)点按 [Build number],直到手机提示你已成为开发者。具体的标签因厂商而异;
- 在 [USB debugging] 中启用 [Developer options] (上一步添加的菜单);
- 使用能传输数据(而不仅仅是充电)的 USB 数据线将手机连接到电脑,并在手机上接受 USB 调试授权请求。在 [Windows] 中,如果手机未被识别,请安装厂商的 USB 驱动程序(“OEM USB drivers”,见 developer.android.com/studio/run/oem-usb);
- 检查电脑是否检测到手机:它应该出现在 [device] 状态下,位于 [adb devices] 显示的列表中(状态 [unauthorized] 表示手机上没有接受授权请求),同时也出现在 [npx cap run android --list] 显示的列表中。
手机将通过电脑在局域网中的 IP 地址访问 [NestJS] 服务器(而不是通过 [localhost],因为从手机的角度看,localhost 就是手机自己):此配置在示例 22 和“部署”一章中有说明。