在 Debian 上解决 Flutter 跨平台问题的实践指南
一 能力边界与总体思路
- 在 Debian 上可以完整完成 Android、Linux、Web 的开发、运行与发布；iOS 的编译与签名必须在 macOS + Xcode 上完成，无法在 Debian 上直接产出 iOS 包。跨平台差异的解决思路包括：统一 Material 3 与 Cupertino 组件风格、按平台设置 Theme 与 PlatformDispatcher、使用 Platform Channels 处理原生能力差异，以及通过 Flutter Desktop 的 Linux 嵌入器适配不同发行版与显示服务器。
二 环境准备与依赖安装
- 安装系统依赖（确保图形、窗口系统与编译链就绪）：
- sudo apt update && sudo apt install -y curl git cmake build-essential pkg-config libegl1-mesa-dev libxkbcommon-dev libgles2-mesa-dev libwayland-dev wayland-protocols
- 获取 Flutter SDK（稳定通道）：
- 方式 A：直接下载并解压稳定版压缩包，解压后将 $HOME/flutter/bin 加入 PATH
- 方式 B：git clone https://github.com/flutter/flutter.git 并加入 PATH
- 初始化与验证：
- flutter doctor（逐项修复缺失项，如 Android SDK/NDK、Chrome、VS Code/Android Studio 等）
- 如需 Android 构建：运行 flutter doctor --android-licenses 接受协议
- 建议同时安装 Android Studio（含 Flutter/ Dart 插件）以便使用 AVD Manager、Logcat、调试器 与设备连接。
三 各平台构建与发布要点
- Android
- 连接真机或启动 AVD，使用 flutter devices 查看设备 ID
- 调试：flutter run -d <device_id>；发布：flutter build apk（或 flutter build appbundle）
- 注意 Gradle 与 AGP 版本匹配，必要时升级 Gradle Wrapper 与插件版本
- Linux（桌面）
- 启用桌面支持：flutter config --enable-linux-desktop
- 运行/构建：flutter run -d linux；flutter build linux
- 发行版差异与渲染后端（如 X11/Wayland）可能导致字体、窗口装饰、输入法差异，需在目标环境实测并调整
- Web
- 启用 Web 支持：flutter config --enable-web
- 运行/构建：flutter run -d chrome；flutter build web
- iOS
- 在 Debian 上无法编译与签名 iOS 应用；将代码同步到 macOS，使用 Xcode 打开 .xcworkspace 构建与归档。
四 常见跨平台问题与对策
- 字体与文本渲染差异
- 统一字体族与字重，使用 TextTheme 的 platform 变体；在 Linux 上优先测试 Noto Sans 等跨平台字体
- 滚动与交互行为
- 通过 ScrollBehavior 与 Material 3 的触摸目标规范统一 iOS/Android/Desktop 的滚动与手势体验
- 平台特定功能
- 使用 Platform Channels 封装原生能力（蓝牙、摄像头、文件系统、通知等），在 Android/iOS/Linux 分别实现与权限适配
- 窗口与系统集成
- Linux 上根据部署环境选择 X11/Wayland，必要时设置窗口属性与系统托盘；Web 上注意 PWA 与 CanvasKit/Skia 渲染差异
- 构建与依赖冲突
- 保持 Flutter/Dart/插件 版本一致；Android 端注意 Gradle/AGP 兼容；Web 端注意 js 互操作 与包体优化
- 持续集成与可复现构建
- 使用 Docker 封装构建环境（示例：基于 Ubuntu 20.04 的容器，预装构建依赖与 Flutter 路径），减少“本机能跑、CI 失败”的环境差异问题。