Valo Documentation
首頁
架構
認證
開發設置
代碼規範
開發流程
故障排除
GitHub
首頁
架構
認證
開發設置
代碼規範
開發流程
故障排除
GitHub
  • 快速開始

    • /
    • 🚀 開發環境設置指南
    • 最初的那些痛
  • 核心概念

    • 🏗️ 專案概述
    • 認證架構文檔
    • 📐 代碼規範
  • 開發指南

    • ⚡ 開發工作流程
    • 🔧 常見問題排解
  • 專案故事

    • 專案故事

🔧 常見問題排解

本文檔收集了 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 路徑不正確或缺少組件

解決方案:

  1. 開啟 Android Studio
  2. 進入 Preferences > Appearance & Behavior > System Settings > Android SDK
  3. 確認 SDK 路徑正確
  4. 安裝必要的 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 代碼簽名失敗

解決方案:

  1. 確認 Apple Developer 帳號設定正確
  2. 在 Xcode 中檢查 Team 設定
  3. 確認 Bundle Identifier 唯一
  4. 檢查證書有效性

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 生成問題

問題: 路由生成失敗或路由不工作

解決方案:

  1. 檢查 app_router.dart 語法
  2. 確認所有頁面都已正確標註
  3. 重新生成路由文件
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 歸檔失敗

解決方案:

  1. 確認 Xcode 中的建制設定正確
  2. 檢查代碼簽名設定
  3. 確認所有依賴都支援目標 iOS 版本

🎯 運行時問題

應用程式啟動問題

白屏或卡住

問題: 應用啟動後顯示白屏或無響應

解決方案:

  1. 檢查控制台錯誤訊息
  2. 確認 Firebase 初始化正常
  3. 檢查主要依賴是否正確載入
// 添加啟動錯誤處理
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 {
  @override
  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 服務

解決方案:

  1. 檢查 Token 是否有效
  2. 確認網路連接正常
  3. 驗證 App ID 和配置
// 添加連接狀態監聽
ChatClient.getInstance.addConnectionEventHandler(
  "connection_handler",
  ConnectionEventHandler(
    onConnected: () {
      print("Connected to Agora Chat");
    },
    onDisconnected: (errorCode) {
      print("Disconnected: $errorCode");
    },
  ),
);

訊息發送失敗

問題: 訊息無法發送

解決方案:

  1. 檢查用戶是否已登入
  2. 確認對話 ID 正確
  3. 檢查網路狀態
// 添加訊息狀態監聽
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 {
  @override
  Widget build(BuildContext context) {
    return Consumer<MyState>(
      builder: (context, state, child) {
        final expensiveData = _computeExpensiveData(state); // ❌ 每次都計算
        return Text(expensiveData);
      },
    );
  }
}

記憶體洩漏

問題: 記憶體使用持續增長

解決方案:

class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  StreamSubscription? _subscription;
  Timer? _timer;
  
  @override
  void initState() {
    super.initState();
    _subscription = stream.listen(onData);
    _timer = Timer.periodic(Duration(seconds: 1), onTimer);
  }
  
  @override
  void dispose() {
    _subscription?.cancel(); // 重要:取消訂閱
    _timer?.cancel(); // 重要:取消計時器
    super.dispose();
  }
}

🐛 調試技巧

日誌和除錯

使用 Flutter Inspector

  1. 在 VS Code 中按 Ctrl+Shift+P
  2. 執行 Flutter: Open Widget Inspector
  3. 檢查 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 {
  @override
  Widget build(BuildContext context) {
    debugPrint('MyWidget is rebuilding');
    return Container();
  }
}

📞 求助管道

內部資源

  1. 文檔: 查看 docs/ 目錄下的相關文檔
  2. 代碼: 參考現有的實現範例
  3. 測試: 查看測試文件了解預期行為

外部資源

  1. Flutter 官方文檔: https://flutter.dev/docs
  2. Agora 文檔: https://docs.agora.io/
  3. Stack Overflow: 搜索相關問題
  4. GitHub Issues: 查看相關套件的問題討論

團隊支援

  1. 技術討論: 在團隊聊天群組中詢問
  2. 代碼審查: 創建 Draft PR 請求協助
  3. 結對編程: 與資深開發者一起解決問題

最後更新: 2025-08-07如果您遇到此文檔未涵蓋的問題,請提交 Issue 或聯繫專案維護者

最後更新: 2025/8/7 中午12:19
貢獻者: boheng
Prev
⚡ 開發工作流程