Initial Flutter project structure、

2026-07-15 12:01:04 +08:00
commit 120525741d
138 changed files with 7888 additions and 0 deletions
@@ -0,0 +1,409 @@
+# Flutter 项目如何写 Android 应用
+
+Flutter 不是“Web 项目”或“Android 项目”分开的。当前项目是一个跨平台 Flutter App，只是当前调试时默认选中了 Web。要写 Android 应用，主要还是写 `lib/` 里的 Flutter 代码，然后用 Android 设备或模拟器运行。
+
+## 核心结论
+
+写 Android App 主要还是写这里：
+
+```text
+lib/
+  main.dart
+  app/
+  features/
+  shared/
+```
+
+不是主要写：
+
+```text
+android/
+```
+
+`android/` 是 Android 原生壳工程，只有在需要权限、包名、签名、原生 SDK 时才改。
+
+## 为什么默认打开是 Web
+
+因为当前环境里 Flutter 可用的设备可能优先显示了 Web，或者 IDE 选择的运行设备是 Chrome / Web。
+
+可以用这个命令看当前可用设备：
+
+```bash
+flutter devices
+```
+
+如果看到类似：
+
+```text
+Chrome (web)
+Linux (desktop)
+Android SDK built for x86
+```
+
+说明 Flutter 可以选择不同平台运行。
+
+运行 Web 是：
+
+```bash
+flutter run -d chrome
+```
+
+运行 Android 是：
+
+```bash
+flutter run -d <android-device-id>
+```
+
+## 要运行 Android 需要准备什么
+
+### 1. Android SDK
+
+当前环境里已经有 Android SDK：
+
+```text
+Android SDK version 37.0.0
+```
+
+这个没问题。
+
+### 2. Android 模拟器或真机
+
+需要至少有一个 Android 设备。
+
+检查：
+
+```bash
+flutter devices
+```
+
+如果没有 Android 设备，需要：
+
+- 打开 Android Studio
+- 启动 Android Emulator
+- 或者连接 Android 手机并打开 USB 调试
+
+## 用真机运行 Android
+
+手机上操作：
+
+1. 打开开发者选项
+2. 打开 USB 调试
+3. 用 USB 连接电脑
+4. 手机弹出授权时点允许
+
+然后电脑运行：
+
+```bash
+flutter devices
+```
+
+如果看到类似：
+
+```text
+xxx device • android-arm64 • Android xx
+```
+
+就可以运行：
+
+```bash
+flutter run -d xxx
+```
+
+如果只有一个 Android 设备，也可以：
+
+```bash
+flutter run
+```
+
+## 用模拟器运行 Android
+
+如果使用 Android Studio：
+
+1. 打开 Android Studio
+2. 打开 Device Manager
+3. 创建一个 Android Virtual Device
+4. 启动模拟器
+5. 回到项目目录运行：
+
+```bash
+flutter devices
+flutter run
+```
+
+或者指定设备：
+
+```bash
+flutter run -d emulator-5554
+```
+
+## Android 应用代码写哪里
+
+Flutter 页面、业务逻辑、状态管理还是写在：
+
+```text
+lib/
+```
+
+例如：
+
+```text
+lib/
+  main.dart
+  app/
+    app.dart
+    theme.dart
+  features/
+    home/
+      home_page.dart
+```
+
+Android 和 Web 会共用这套 Dart 代码。
+
+也就是说，写：
+
+```dart
+Scaffold(
+  appBar: AppBar(title: const Text('首页')),
+  body: const Center(child: Text('这是 Android App')),
+)
+```
+
+它既可以跑在 Android，也可以跑在 Web。只是最终运行目标不同。
+
+## 什么时候才需要改 `android/`
+
+平时不要一开始就去 `android/` 写代码。
+
+只有这些情况需要改：
+
+### 1. 改 Android 包名
+
+比如从默认包名改成：
+
+```text
+com.yourcompany.patbond
+```
+
+会涉及：
+
+```text
+android/app/build.gradle.kts
+android/app/src/main/AndroidManifest.xml
+android/app/src/main/kotlin/...
+```
+
+### 2. 加 Android 权限
+
+比如相机、相册、定位、网络、蓝牙。
+
+一般改：
+
+```text
+android/app/src/main/AndroidManifest.xml
+```
+
+例如网络权限：
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+```
+
+定位权限：
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+### 3. 配置应用图标和启动页
+
+常见会用插件：
+
+```text
+flutter_launcher_icons
+flutter_native_splash
+```
+
+### 4. 配置签名打包
+
+发布 APK / AAB 时需要改 Android 签名配置。
+
+常见文件：
+
+```text
+android/key.properties
+android/app/build.gradle.kts
+```
+
+### 5. 接入原生 SDK
+
+比如：
+
+- 微信登录
+- 支付宝支付
+- 高德地图
+- 极光推送
+- Firebase
+- 原生蓝牙能力
+
+## 现在应该怎么开始写 Android App
+
+建议顺序：
+
+1. 先把运行设备切到 Android
+
+```bash
+flutter devices
+```
+
+然后选择 Android 设备运行：
+
+```bash
+flutter run -d 设备ID
+```
+
+2. 不要改 `android/`，先写 `lib/`
+
+把默认计数器 Demo 替换成自己的首页。
+
+3. 按这个结构开始：
+
+```text
+lib/
+  main.dart
+  app/
+    app.dart
+    theme.dart
+  features/
+    home/
+      home_page.dart
+```
+
+4. 如果后面需要接口，再加：
+
+```text
+lib/core/network/
+```
+
+5. 如果需要登录，再加：
+
+```text
+lib/features/auth/
+```
+
+6. 如果需要 Android 权限，再去改：
+
+```text
+android/app/src/main/AndroidManifest.xml
+```
+
+## Android 和 Web 写法有什么区别
+
+大部分 UI 和业务代码一样。
+
+但是有些能力要注意平台差异：
+
+```text
+相机
+相册
+定位
+蓝牙
+文件系统
+推送
+支付
+扫码
+后台服务
+本地通知
+```
+
+这些功能在 Android 上通常需要：
+
+- Flutter 插件
+- Android 权限
+- 有时还需要 Android 原生配置
+
+例如访问相机，可能需要：
+
+```yaml
+dependencies:
+  image_picker: ^x.x.x
+```
+
+然后 AndroidManifest 里配置权限。
+
+## 如何确认现在运行的是 Android
+
+运行成功后，终端会显示类似：
+
+```text
+Launching lib/main.dart on Android SDK built for x86 in debug mode...
+```
+
+如果是 Web，则会显示：
+
+```text
+Launching lib/main.dart on Chrome in debug mode...
+```
+
+所以看这一行就知道当前跑在哪个平台。
+
+## 常用命令
+
+查看设备：
+
+```bash
+flutter devices
+```
+
+运行到 Android：
+
+```bash
+flutter run -d <android-device-id>
+```
+
+运行到 Chrome：
+
+```bash
+flutter run -d chrome
+```
+
+构建 Android APK：
+
+```bash
+flutter build apk
+```
+
+构建 Android App Bundle，发布 Google Play 用：
+
+```bash
+flutter build appbundle
+```
+
+清理构建缓存：
+
+```bash
+flutter clean
+```
+
+重新拉依赖：
+
+```bash
+flutter pub get
+```
+
+## 建议先做这一步
+
+先运行：
+
+```bash
+flutter devices
+```
+
+如果能看到 Android 设备，就用它的 ID 运行：
+
+```bash
+flutter run -d 设备ID
+```
+
+如果看不到 Android 设备，那不是代码问题，是还没有连接真机或启动模拟器。
+
+代码开发上，继续写 `lib/` 即可。Flutter 的 Android App 本质上就是这套 Dart UI 跑在 Android 容器里。