Flutter Integration in Mixed Native Projects: Architecture, Build Optimization, and Debugging

This article documents the complete reconstruction of the product detail page in the Xianyu app using Flutter, describing the lessons learned from the alpha stage to production.

The series consists of three parts: introduction (project engineering system), runtime (stack management and capability completion in hybrid scenarios), and release (compatibility and stability guarantees).

Engineering system highlights :

a. Flutter development structure in hybrid projects.

b. How to introduce Flutter into existing native iOS/Android projects, organize the project structure, manage the Flutter environment, and handle compilation and packaging.

c. Build optimization, focusing on debugging and performance tuning of the Flutter toolchain (flutter_tools, IDE plugins, etc.).

d. Separate debugging when Flutter is launched from a native app (Xcode/Android Studio), which simplifies flutter_tools complexity and improves stability.

e. Hot‑reload handling under native launch.

f. Joint debugging of Flutter and native code.

g. Continuous integration for hybrid builds.

Environment : The Flutter module is treated as an independent library (pod for iOS, AAR for Android) and integrated via CocoaPods or Gradle. The whole Flutter environment is managed as a Git submodule to ensure consistency across the team.

Build optimization – Android :

Problem: Slow builds when Flutter is launched from Android because flutter_tools looks for android/app/build.gradle and falls back to a full Gradle build.

Solution: Restructure the Android project so that the module’s build.gradle resides under android/app, aligning with flutter_tools expectations.

Additional steps include modifying flutter_tools.dart to print parameters, clearing the Flutter cache, extracting entry parameters, and creating a Dart command‑line app in IntelliJ to reproduce the build flow.

Build optimization – iOS :

Problem: Build interruption caused by the IntelliJ Flutter plugin timeout when compilation exceeds 10 minutes.

Solutions (from low to high):

1) Patch the plugin source to increase the timeout (temporary).

2) Split iOS modules into pre‑compiled frameworks (pod‑based) to drastically reduce build time.

3) Use native‑launch debugging to avoid reliance on flutter_tools for hot‑reload.

Native‑launch debugging workflow :

1) Verify whether a new flutter_tools.snapshot is needed.

2) Run pub get to generate .flutter-plugins and pubspec.lock.

3) Generate platform‑specific config files ( Generated.xcconfig for iOS, local.properties for Android).

4) Build the app with Gradle or xcodebuild.

5) Launch the app via adb (Android) or lldb (iOS).

6) Detect the Observatory port, forward it to the host, and attach the Dart debugger.

7) Use the forwarded port to perform full restart or hot‑reload.

The same approach works for both iOS (using idevicesyslog and iproxy) and Android (using adb logcat and adb forward).

Hot‑reload under native launch :

Start the app, locate the Observatory port, forward it, then run flutter attach --debug-port=<forwarded_port>. Modify Dart code, press r in the terminal, and the changes are applied instantly.

Continuous Integration :

A shared Mac Mini hosts the Flutter environment, builds AAR/pod artifacts, and publishes them for native CI pipelines to consume, ensuring consistent builds for both Android and iOS.

Conclusion : The article outlines a systematic engineering approach for hybrid Flutter projects, covering project structure, build optimization, native‑launch debugging, hot‑reload, and CI integration. Future articles will address runtime challenges such as stack management, platform‑specific feature gaps, and plugin/package management.