Flutter卡在“Waiting for VM Service port to be available...”问题求助

问题场景 #

为应用添加组件后，执行了Gradle同步、升级Gradle插件、升级SDK、修改Android目录下多文件，还更新了Android Studio并迁移了Android SDK目录。现在应用完全无法启动，执行flutter run -v后，终端一直停留在“Waiting for VM Service port to be available...”状态。已确认包名正确、MainActivity.kt无异常，尝试过重装重启相关工具（除VSCode）仍未解决。flutter run -v最后输出内容如下：

[   +3 ms] Installing build\app\outputs\flutter-apk\app-debug.apk...
[   +1 ms] executing: D:\Brockdish\Programming\SDKs\Android\platform-tools\adb.exe -s emulator-5554 install -t -r D:\Brockdish\Programming\Flutter
Projects\clothes_ethics_app\build\app\outputs\flutter-apk\app-debug.apk
[+7765 ms] Performing Streamed Install
                    Success
[   +2 ms] Installing build\app\outputs\flutter-apk\app-debug.apk... (completed in 7,8s)
[   +5 ms] executing: D:\Brockdish\Programming\SDKs\Android\platform-tools\adb.exe -s emulator-5554 shell echo -n d613de727cfacda75e7bd4e15d3f720ebf3e7c66 >
/data/local/tmp/sky.dev.jusoft.clotho.sha1
[ +218 ms] executing: D:\Brockdish\Programming\SDKs\Android\platform-tools\adb.exe -s emulator-5554 shell -x logcat -v time -t 1
[+1482 ms] --------- beginning of main
                    09-05 18:36:18.886 D/ControlsListingControllerImpl( 1065): ServiceConfig reloaded, count: 0
[ +162 ms] executing: D:\Brockdish\Programming\SDKs\Android\platform-tools\adb.exe -s emulator-5554 shell am start -a android.intent.action.MAIN -c android.intent.category.LAUNCHER -f
0x20000000 --ez enable-dart-profiling true --ez enable-checked-mode true --ez verify-entry-points true dev.jusoft.clotho/dev.jusoft.clotho.MainActivity
[+4143 ms] Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] flg=0x20000000 cmp=dev.jusoft.clotho/.MainActivity (has extras) }
[   +2 ms] Waiting for VM Service port to be available...

排查与解决步骤 #

1. 修复ADB连接异常 #

• 执行adb kill-server，再执行adb start-server重启ADB服务，解决可能的连接阻塞问题
• 检查ADB默认端口5037是否被占用：Windows执行netstat -ano | findstr :5037，Mac/Linux执行lsof -i :5037，若有占用则结束对应进程后重启ADB
• 更换模拟器或使用真实物理设备测试，排除模拟器本身的兼容性问题

2. 彻底清理构建缓存 #

• 执行flutter clean清理Flutter层面的构建缓存
• 进入项目的android目录，执行gradlew clean（Windows）或./gradlew clean（Mac/Linux）清理Gradle缓存
• 删除项目根目录下的.dart_tool、build文件夹，以及Android目录下的.gradle、build文件夹，强制重新构建

3. 校验SDK与Gradle配置一致性 #

• 打开android/build.gradle，确认Gradle插件版本与gradle/wrapper/gradle-wrapper.properties中的Gradle版本匹配（可参考官方兼容对照表）
• 检查local.properties中的sdk.dir路径是否与迁移后的Android SDK目录完全一致，避免路径错误导致资源加载失败
• 执行flutter doctor -v排查所有依赖配置问题，修复输出中提示的异常项（如缺失的SDK组件、权限问题等）

4. 抓取启动阶段详细日志 #

• 单独执行adb logcat -v time，手动启动应用，重点关注AndroidRuntime、Flutter相关的报错信息，定位类找不到、资源缺失、权限冲突等启动异常
• 检查是否有新添加组件导致的初始化错误，比如未正确配置的第三方库、缺失的权限声明

5. 重置Flutter环境配置 #

• 执行flutter config --clear重置Flutter全局配置
• 重新指定Android SDK路径：flutter config --android-sdk <你的SDK绝对路径>
• 执行flutter pub get重新拉取所有依赖，再尝试构建运行

6. 检查AndroidManifest.xml配置 #

• 确认AndroidManifest.xml中MainActivity的intent-filter配置正确，包含android.intent.action.MAIN动作和android.intent.category.LAUNCHER类别
• 检查是否添加了新组件所需的权限声明，或存在配置冲突（如重复的Activity声明）

内容的提问来源于stack exchange，提问作者Brockdish