🔧 常見問題排解
本文檔收集了 Valo 專案開發過程中常見的問題和解決方案,幫助開發者快速解決遇到的困難。
🚀 開發環境問題
Flutter 相關問題
Flutter Doctor 報告問題
問題: flutter doctor
顯示錯誤或警告
解決方案:
# Android license 問題
flutter doctor --android-licenses
# iOS 問題 (macOS)
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
# 重新檢查
flutter doctor -v
Flutter 版本不符
問題: Flutter 版本過舊或不相容
解決方案:
# 升級 Flutter
flutter upgrade
# 切換到特定版本(如需要)
flutter downgrade
# 檢查版本
flutter --version
Android 開發環境
Gradle 建制失敗
問題: Android 建制時出現各種 Gradle 錯誤
解決方案:
# 清理建制快取
cd android
./gradlew clean
cd ..
# 清理 Flutter 快取
flutter clean
flutter pub get
# 如果仍有問題,刪除建制資料夾
rm -rf build/
rm -rf android/build/
rm -rf android/app/build/
Java 版本問題
問題: Java 版本不相容
解決方案:
# 檢查 Java 版本(需要 Java 11)
java --version
# macOS 設定 JAVA_HOME
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
# 永久設定(添加到 ~/.bashrc 或 ~/.zshrc)
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 11)' >> ~/.zshrc
Android SDK 問題
問題: SDK 路徑不正確或缺少組件
解決方案:
- 開啟 Android Studio
- 進入
Preferences > Appearance & Behavior > System Settings > Android SDK
- 確認 SDK 路徑正確
- 安裝必要的 SDK 組件(API 21+)
模擬器無法啟動
問題: Android 模擬器啟動失敗
解決方案:
# 檢查虛擬化支援
# 在 BIOS 中啟用 Intel VT-x 或 AMD-V
# 冷啟動模擬器
# 在 AVD Manager 中點擊下拉選單選擇 "Cold Boot Now"
# 增加模擬器記憶體
# 在 AVD Manager 中編輯模擬器,增加 RAM 和 Internal Storage
iOS 開發環境
CocoaPods 問題
問題: Pod 安裝失敗或衝突
解決方案:
# 清理並重新安裝 pods
cd ios
rm -rf Pods Podfile.lock
pod repo update
pod install
cd ..
# M1 Mac 特殊處理
sudo arch -x86_64 gem install ffi
arch -x86_64 pod install
Xcode 建制問題
問題: Xcode 建制失敗
解決方案:
# 清理 Xcode 建制快取
cd ios
rm -rf build/
xcodebuild clean
cd ..
# 重新安裝依賴
flutter clean
flutter pub get
cd ios && pod install && cd ..
代碼簽名問題
問題: iOS 代碼簽名失敗
解決方案:
- 確認 Apple Developer 帳號設定正確
- 在 Xcode 中檢查 Team 設定
- 確認 Bundle Identifier 唯一
- 檢查證書有效性
Firebase 設定問題
配置文件缺失
問題: Firebase 配置文件不存在或路徑錯誤
解決方案:
- Android: 確認
android/app/google-services.json
存在 - iOS: 確認
ios/Runner/GoogleService-Info.plist
存在 - 從 Firebase Console 重新下載配置文件
Firebase 服務初始化失敗
問題: Firebase 服務無法初始化
解決方案:
// 確認 main.dart 中正確初始化
await Firebase.initializeApp(
options: DefaultFirebaseOptions.currentPlatform,
);
🔧 建制和部署問題
代碼生成問題
Build Runner 失敗
問題: 自動代碼生成失敗
解決方案:
# 清理生成的文件
flutter packages pub run build_runner clean
# 重新生成
flutter packages pub run build_runner build --delete-conflicting-outputs
# 如果仍失敗,檢查語法錯誤
flutter analyze
Auto Route 生成問題
問題: 路由生成失敗或路由不工作
解決方案:
- 檢查
app_router.dart
語法 - 確認所有頁面都已正確標註
- 重新生成路由文件
flutter packages pub run build_runner build --build-filter="*.gr.dart"
發布建制問題
Android Release 建制失敗
問題: 發布版本建制失敗
解決方案:
# 檢查簽名配置
# 確認 android/key.properties 存在且正確
# 清理並重試
flutter clean
flutter pub get
flutter build appbundle --release
iOS Archive 失敗
問題: iOS 歸檔失敗
解決方案:
- 確認 Xcode 中的建制設定正確
- 檢查代碼簽名設定
- 確認所有依賴都支援目標 iOS 版本
🎯 運行時問題
應用程式啟動問題
白屏或卡住
問題: 應用啟動後顯示白屏或無響應
解決方案:
- 檢查控制台錯誤訊息
- 確認 Firebase 初始化正常
- 檢查主要依賴是否正確載入
// 添加啟動錯誤處理
runZonedGuarded(() {
runApp(MyApp());
}, (error, stack) {
print('App crashed: $error');
});
環境變數問題
問題: 環境變數未正確載入
解決方案:
# 確認環境文件存在
ls -la .env*
# 檢查 dart-define 參數
flutter run --dart-define=ENV=dev --verbose
# 確認環境文件內容格式正確
網路連接問題
API 請求失敗
問題: API 請求超時或失敗
解決方案:
// 增加超時設定和重試機制
final dio = Dio(BaseOptions(
connectTimeout: 10000,
receiveTimeout: 10000,
sendTimeout: 10000,
));
// 添加重試攔截器
dio.interceptors.add(RetryInterceptor(
dio: dio,
options: const RetryOptions(
retries: 3,
retryInterval: Duration(seconds: 1),
),
));
HTTPS 憑證問題
問題: HTTPS 請求因憑證問題失敗
解決方案:
// 僅在開發環境中使用,生產環境必須移除
import 'dart:io';
class MyHttpOverrides extends HttpOverrides {
HttpClient createHttpClient(SecurityContext? context) {
return super.createHttpClient(context)
..badCertificateCallback = (X509Certificate cert, String host, int port) => true;
}
}
// 在 main.dart 中(僅開發環境)
if (kDebugMode) {
HttpOverrides.global = MyHttpOverrides();
}
Agora Chat SDK 問題
連接失敗
問題: 無法連接到 Agora Chat 服務
解決方案:
- 檢查 Token 是否有效
- 確認網路連接正常
- 驗證 App ID 和配置
// 添加連接狀態監聽
ChatClient.getInstance.addConnectionEventHandler(
"connection_handler",
ConnectionEventHandler(
onConnected: () {
print("Connected to Agora Chat");
},
onDisconnected: (errorCode) {
print("Disconnected: $errorCode");
},
),
);
訊息發送失敗
問題: 訊息無法發送
解決方案:
- 檢查用戶是否已登入
- 確認對話 ID 正確
- 檢查網路狀態
// 添加訊息狀態監聽
final message = ChatMessage.createTxtSendMessage(
targetId: conversationId,
content: content,
);
message.setMessageStatusCallBack(MessageStatusCallBack(
onSuccess: () {
print("Message sent successfully");
},
onError: (error) {
print("Message failed: ${error.description}");
},
));
狀態管理問題
Provider 狀態不更新
問題: UI 沒有響應狀態變化
解決方案:
// 確認正確調用 notifyListeners()
class MyState extends ChangeNotifier {
String _data = '';
set data(String value) {
_data = value;
notifyListeners(); // 重要:通知監聽者
}
}
// 使用 Selector 而非 Consumer
Selector<MyState, String>(
selector: (context, state) => state.data,
builder: (context, data, child) {
return Text(data);
},
)
Context 相關錯誤
問題: BuildContext 使用錯誤
解決方案:
// 異步操作中檢查 mounted
Future<void> fetchData() async {
final data = await api.getData();
if (mounted) {
setState(() {
this.data = data;
});
}
}
// 正確使用 context.read() 和 context.watch()
// build 方法中用 watch,事件處理中用 read
性能問題
應用程式卡頓
問題: UI 響應緩慢或卡頓
解決方案:
// 使用 ListView.builder 代替 Column
ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) {
return ItemWidget(item: items[index]);
},
)
// 使用 const 建構函數
const MyWidget({Key? key}) : super(key: key);
// 避免在 build 方法中進行重計算
class MyWidget extends StatelessWidget {
Widget build(BuildContext context) {
return Consumer<MyState>(
builder: (context, state, child) {
final expensiveData = _computeExpensiveData(state); // ❌ 每次都計算
return Text(expensiveData);
},
);
}
}
記憶體洩漏
問題: 記憶體使用持續增長
解決方案:
class MyWidget extends StatefulWidget {
_MyWidgetState createState() => _MyWidgetState();
}
class _MyWidgetState extends State<MyWidget> {
StreamSubscription? _subscription;
Timer? _timer;
void initState() {
super.initState();
_subscription = stream.listen(onData);
_timer = Timer.periodic(Duration(seconds: 1), onTimer);
}
void dispose() {
_subscription?.cancel(); // 重要:取消訂閱
_timer?.cancel(); // 重要:取消計時器
super.dispose();
}
}
🐛 調試技巧
日誌和除錯
使用 Flutter Inspector
- 在 VS Code 中按
Ctrl+Shift+P
- 執行
Flutter: Open Widget Inspector
- 檢查 Widget 樹和屬性
使用 print 和 debugPrint
// 開發環境中使用
import 'package:flutter/foundation.dart';
void debugLog(String message) {
if (kDebugMode) {
debugPrint('[Debug] $message');
}
}
使用 Logger 包
import 'package:logger/logger.dart';
final logger = Logger();
logger.d('Debug message');
logger.i('Info message');
logger.w('Warning message');
logger.e('Error message');
效能分析
使用 Flutter Performance 工具
# 啟動效能監控
flutter run --profile
# 在 DevTools 中查看效能資料
flutter pub global run devtools
檢查 Widget 重建
// 添加調試輸出
class MyWidget extends StatelessWidget {
Widget build(BuildContext context) {
debugPrint('MyWidget is rebuilding');
return Container();
}
}
📞 求助管道
內部資源
- 文檔: 查看
docs/
目錄下的相關文檔 - 代碼: 參考現有的實現範例
- 測試: 查看測試文件了解預期行為
外部資源
- Flutter 官方文檔: https://flutter.dev/docs
- Agora 文檔: https://docs.agora.io/
- Stack Overflow: 搜索相關問題
- GitHub Issues: 查看相關套件的問題討論
團隊支援
- 技術討論: 在團隊聊天群組中詢問
- 代碼審查: 創建 Draft PR 請求協助
- 結對編程: 與資深開發者一起解決問題
最後更新: 2025-08-07如果您遇到此文檔未涵蓋的問題,請提交 Issue 或聯繫專案維護者