Android 开发环境搭建（Windows）

本文面向从零配置本仓库的 Windows 开发机。其他系统的安装步骤请参考 Flutter 官方 Android 配置指南。

1. 准备工具

安装 Git，以便获取代码。
安装 Flutter SDK，并将 SDK 的 bin 目录加入用户 Path。本仓库要求 Flutter 3.47.5，对应 Dart 3.13.4。仅安装 Android Studio 的 Flutter 插件并不包含 Flutter SDK。
安装 Android Studio。建议在安装向导中安装 Android SDK 和 Android Emulator；用 Android Studio 编写 Flutter 代码时，再从 Settings > Plugins 安装 Flutter 插件（会提示安装 Dart 插件）。只用命令行或其他编辑器时，IDE 插件不是必需的。
准备 JDK 17 或更新版本。可先使用 Android Studio 提供的 JDK；若 Gradle 报 Java 版本或路径错误，用 flutter doctor -v 查看当前 Java 路径，再通过 flutter config --jdk-dir="JDK安装目录" 指定可用 JDK。

重新打开 PowerShell，检查命令及版本：

git --version
flutter --version
flutter doctor -v

flutter --version 应显示 3.47.5。版本不一致时先切换到该版本，再执行仓库脚本；脚本会拒绝其他版本。

2. 安装 Android SDK 组件

打开 Android Studio 的 Tools > SDK Manager（欢迎页可从 More Actions > SDK Manager 进入）：

SDK Platforms：安装 Android API 36。
SDK Tools：安装 Android SDK Build-Tools 36.0.0、Android SDK Platform-Tools、Android SDK Command-line Tools (latest)、Android Emulator、NDK (Side by side) 28.2.13676358 和 CMake 3.22.1。勾选 Show Package Details 才能选择指定的 NDK、CMake 和 Build-Tools 版本。

在 PowerShell 中查看并接受 SDK 许可：

flutter doctor --android-licenses
flutter doctor -v

逐条阅读许可并按提示确认。flutter doctor -v 的 Android toolchain 应通过，并显示 Android SDK 的实际路径。只开发 Android 时，Windows 桌面开发所需的 Visual Studio 检查项可以不通过。

项目使用 Android Gradle Plugin 9.1.0 和仓库内的 Gradle Wrapper 9.3.1；构建时会自动使用 Wrapper，无须单独安装 Gradle。首次构建需要网络下载 Gradle、Android 插件及依赖。

3. 获取代码和依赖

在仓库根目录执行（将路径替换成自己的目录）：

cd E:\uninote\mynote-mobile
.\tool\bootstrap.ps1

脚本先检查 Flutter 版本，然后运行 flutter clean 和 flutter pub get。这会重新生成本机 Flutter 构建缓存。已有正确版本且无需清理时，可直接运行 flutter pub get。

android/local.properties 是本机生成的文件，不应提交；其中的 sdk.dir 和 flutter.sdk 应指向本机 SDK 路径。如果 Gradle 提示找不到 Flutter SDK，先运行 flutter pub get，再检查该文件和 flutter doctor -v 显示的路径。

4. 准备 Android 设备

模拟器

确保电脑已启用虚拟化。Windows 模拟器加速配置见 Android 官方文档。
在 Android Studio 的 Tools > Device Manager 中选择 Create Virtual Device，选择设备和 Android 系统镜像，下载后启动。
在 PowerShell 中确认模拟器已连接：
```
flutter emulators
flutter devices
```

真机

在手机的开发者选项中开启 USB 调试，用数据线连接电脑，并在手机上允许该电脑调试。
Windows 如未识别设备，安装厂商提供的 OEM USB 驱动。
执行 flutter devices。设备应显示为 Android 设备；若提示 unauthorized，在手机上确认授权后重试。

5. 运行和调试

在仓库根目录运行：

flutter devices
flutter run -d <设备ID>

将 <设备ID> 替换为 flutter devices 列出的 ID，例如 emulator-5554。只有一台可用设备时也可直接运行 flutter run。运行期间在终端按 r 热重载、按 R 热重启、按 q 退出。

应用启动后可以直接新建本地笔记库。登录远端同步服务时填写手机或模拟器能够访问的 HTTPS 服务地址；应用仅允许 localhost、127.0.0.1、::1 使用 HTTP。这些地址在设备上指向设备自身，不是开发电脑。连接电脑上的服务时，应提供设备可访问的 HTTPS 地址，并确保网络和防火墙允许连接。当前开发版本预填测试登录信息，发布或共享构建前必须删除。

6. 验证与构建

flutter analyze
flutter test
flutter build apk --debug
flutter build apk --release

APK 位于 build/app/outputs/flutter-apk/。当前 release 配置使用调试签名，仅供安装验证；正式发布前须按 Flutter Android 发布指南配置发布签名。

常见问题

flutter 不是可识别的命令：确认 Flutter SDK 的 bin 已加入 Path，然后重新打开终端。
Android licenses 未接受或状态未知：确认安装了 Android SDK Command-line Tools (latest)，再执行 flutter doctor --android-licenses。
找不到 SDK、NDK、CMake 或 Build-Tools：检查 SDK Manager 中的指定版本、flutter doctor -v 所示 SDK 路径，以及 android/local.properties 的本机路径。
模拟器无法启动或运行很慢：检查 BIOS/UEFI 虚拟化及 Windows 模拟器加速配置。
flutter devices 看不到手机：检查 USB 调试授权、数据线传输模式和 Windows OEM USB 驱动。
首次构建下载失败：确认可以访问 Google Maven、Maven Central、Gradle 分发站点及 Flutter 依赖源，再重试构建。
插件缺失或本机缓存异常：确认 Flutter 版本后重新执行 .\tool\bootstrap.ps1。
Kotlin 增量缓存报 Storage ... is already registered：仓库已关闭 Kotlin 增量编译以规避 url_launcher_android 的 release 编译缓存错误；Kotlin 编译可能较慢。
Codex Windows 环境中 Gradle 启动时报 Unable to establish loopback connection：2026-09-30 已用 Java Selector.open() 独立复现，错误发生在项目编译前。在同一执行环境中不要反复尝试打包；可继续运行 flutter analyze 和 flutter test。环境更新后再验证打包，或在普通 PowerShell 中尝试构建。

android-development