Windows Android Studio + WSL Flutter — Compatibility Orchestration Layer v3.1 — Seamlessly bridge Windows IDE with WSL Flutter toolchain. Diagnose, repair, and manage.
FlutterWrapper lets Android Studio on Windows use a Flutter SDK installed inside WSL2 — without installing Flutter on Windows.
It simulates a Flutter SDK directory structure, transparently forwards all flutter/dart commands to WSL, and translates paths bidirectionally so the IDE never knows the difference.
Android Studio → flutter.bat → flutter.ps1 → wsl.exe → WSL Flutter
↑ Windows paths ↔ WSL paths translated ↑
git clone https://github.com/berial/FlutterWrapper.git %USERPROFILE%\FlutterWrapper
powershell -NoProfile -ExecutionPolicy Bypass -File %USERPROFILE%\FlutterWrapper\install.ps1 -Auto
%USERPROFILE%\FlutterWrapper\bin\fw.bat doctor- Settings → Languages & Frameworks → Flutter → SDK path:
%USERPROFILE%\FlutterWrapper - Settings → Languages & Frameworks → Dart → SDK path:
%USERPROFILE%\FlutterWrapper\bin\cache\dart-sdk ⚠️ Open WSL projects via mapped drive:W:\home\<user>\<project>— NOT UNC\\wsl.localhost\...
fw doctor # 13-category diagnostic
fw doctor --fix-safe # diagnose + auto-repair safe items
fw repair dart-sdk # repair specific component
fw repair --list # list all repair modules
fw provider # show SDK manager (vfox/FVM)
fw flutter current # current Flutter version
fw flutter use 3.44.6 # switch version (routes to provider)
fw status # quick summary| Layer | What | Detail |
|---|---|---|
| SDK Proxy | Simulates Flutter SDK | flutter.bat, dart.bat, Junction to Windows dart-sdk, pubspec.yaml stub |
| Command Bridge | Forwards to WSL | flutter.ps1/dart.ps1 → wsl.exe -e flutter/dart |
| Path Translation | Bidirectional | D:\x ↔ /mnt/d/x, \\wsl.localhost\... ↔ /home/... |
| Daemon Translator | TCP JSON-RPC | wrapper.ps1 — two-Runspace text-mode bridge on port 9876 |
| Dart Analysis | Dual-track | Windows dart.exe via Junction for IDE; WSL symlinks for compiler |
| Android Bridge | Hybrid toolchain | Windows SDK + WSL Linux NDK/cmake via local.properties |
| Gradle Adapter | Mirror + cache | Aliyun Maven mirror, dists symlink sharing |
| Feature | Description |
|---|---|
| One-command install | install.ps1 -Auto detects WSL, Flutter (vfox/FVM), JDK, Android SDK, generates config |
| Diagnostics | fw doctor checks 13 categories with fix suggestions |
| Auto-repair | fw repair <module> — 7 idempotent modules (package-config, dart-sdk, symlinks, config, vfox, daemon, cache) |
| Provider integration | Detects and integrates with vfox / FVM, not replaces them |
| Split logging | logs/flutter.log / dart.log / bridge.log by command type |
| UTF-8 safe | Full chain UTF-8, handles CJK paths and emoji |
- Modular doctor:
lib/doctor/check-*.ps1— 13 check categories in 4 focused modules - Provider adapters:
lib/providers/vfox.ps1+fvm.ps1— plugin architecture for SDK managers - Diagnostic reports:
fw doctor --collectgeneratesflutterwrapper-report.zipfor GitHub issues - CI pipeline: PowerShell syntax check, ShellCheck, smoke test on every push
- VERSION file: single source of truth, read by all scripts
| Component | Supported |
|---|---|
| Windows | 10 / 11 |
| WSL | Ubuntu 22.04 / 24.04, Debian |
| Flutter | 3.22+ (3.44+ recommended) |
| Android Studio | Koala / Ladybug / Quail |
| SDK Manager | vfox, FVM |
MIT — see LICENSE.