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
dart run tool/flutter_with_metadata.dart run -d <设备ID>

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

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

6. 验证与构建

flutter analyze
flutter test
dart run tool/flutter_with_metadata.dart build apk --debug
dart run tool/flutter_with_metadata.dart build apk --release

关于窗口的构建信息

脚本支持 run 和 build，转发 Flutter 参数、终端交互、输出与退出码；Android 和 iOS 共用该 Dart 脚本。
默认读取 pubspec.yaml 的版本和构建号；可用 --build-name=1.2.3 --build-number=42 覆盖。
- 同时支持空格形式，例如 --build-name 1.2.3；显示信息与传给 Flutter 的版本参数保持一致。
Git 提交记录短哈希（至少 7 位，冲突时由 Git 自动加长）和未提交改动标记；Git 不可用时显示“未提供”，不阻止构建。
构建时间为本次构建采集元数据时的 UTC 时间；系统版本在设备上读取，关于窗口和复制内容不包含 Flutter、Dart 版本。
构建信息通过 MYNOTE_ 前缀的 --dart-define 注入，不生成受 Git 跟踪的文件；该前缀由脚本管理。
普通 flutter run/build 同样自动注入信息：Android 通过 Gradle，iOS 通过 Xcode 构建脚本采集。两个平台复用 Dart 元数据采集器，构建期间不会递归调用 Flutter。更新诊断信息需要重新构建；已安装的应用需安装新包并重启，仅热重载不会重新采集构建信息。
Windows 下脚本自动创建 build/java-sockets，仅为 Flutter 子进程追加 -Djdk.net.unixdomain.tmpdir，保留已有 JAVA_TOOL_OPTIONS，不修改全局 Java 配置。
iOS 构建和设备验证仍需 macOS 与 Xcode。

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：该问题曾由 Java Selector.open() 的 Unix socket 临时目录触发。2026-10-22 已验证项目内 build/java-sockets 绕法有效，统一构建脚本自动应用此配置；直接运行 Flutter 或 Gradle 时按项目 AGENTS.md 设置进程级 Java 参数。 flutter clean 后需要重新创建该目录；仍失败时保留实际错误，并继续执行分析和测试。

android-development