安裝故障排除

本頁描述了一些新 Flutter 使用者遇到的常見安裝問題，並提供瞭解決這些問題的建議。

如果您在使用本頁後仍然遇到問題，請考慮聯絡社群支援渠道中列出的任何資源。要向本頁新增主題或進行更正，您可以在 GitHub 上提交問題或提交拉取請求。

此問題表現為何？

當您嘗試執行 flutter 命令時，控制檯無法找到它。錯誤通常如下所示

'flutter' is not recognized as an internal or external command operable program or batch file

macOS 和 Linux 上的錯誤訊息可能與 Windows 上的略有不同。

解釋和建議

您是否將 Flutter 新增到您平臺的 PATH 環境變數中？在 Windows 上，請按照這些將命令新增到路徑的說明進行操作。

如果您已經為 Flutter 開發設定了 VS Code，您可以使用 Flutter 擴充套件的 Locate SDK 提示來識別您的 flutter 資料夾的位置。

另請參閱：配置 PATH 和環境變數 - Dart Code

此問題表現為何？

執行您的 Flutter 專案會產生如下錯誤

The Flutter SDK is installed in a protected folder and may not function correctly.
Please move the SDK to a location that is user-writable without Administration permissions and restart.

解釋和建議

在 Windows 上，這通常發生在 Flutter 安裝在需要提升許可權的目錄（如 C:\Program Files\）中時。嘗試將 Flutter 重新定位到不同的資料夾，例如 C:\src\flutter。

此問題表現為何？

命令 flutter doctor --android-licenses 失敗。執行 flutter doctor --verbose 會出現如下錯誤訊息

java.lang.UnsupportedClassVersionError: com/android/prefs/AndroidLocationsProvider
has been compiled by a more recent version of the Java Runtime (class file version 55.0),
this version of the Java Runtime only recognizes class file versions up to 52.0

解釋和建議

當您的計算機上安裝了舊版本的 Java Development Kit (JDK) 時，會發生此錯誤。

如果您不需要多個版本的 Java，請從您的計算機上解除安裝現有的 JDK。Flutter 會自動使用 Android Studio 中包含的 JDK。

如果您確實需要另一個版本的 Java，請嘗試此 GitHub 問題中描述的解決方法，直到實施長期解決方案。有關更多資訊，請檢視Android Java Gradle 遷移指南或flutter doctor --android-licenses 因 java.lang.UnsupportedClassVersionError 而無法工作 - Stack Overflow。

此問題表現為何？

flutter doctor 命令抱怨 Android 工具鏈中缺少 cmdline-tools。例如

[!] Android toolchain - develop for Android devices (Android SDK version 33.0.2)
    • Android SDK at C:\Users\My PC\AppData\Local\Android\sdk
    X cmdline-tools component is missing

解釋和建議

獲取 cmdline-tools 最簡單的方法是透過 Android Studio 中的 SDK 管理器。為此，請使用以下說明

1. 從選單欄中選擇 Tools > SDK Manager，從 Android Studio 開啟 SDK 管理器。
2. 選擇最新的 Android SDK（或您的應用所需的特定版本）、Android SDK Command-line Tools 和 Android SDK Build-Tools。
3. 單擊 Apply 安裝選定的工件。

如果您不使用 Android Studio，您可以使用 sdkmanager 命令列工具下載這些工具。

此問題表現為何？

在 macOS 上，flutter run 命令會產生如下錯誤

$ flutter run
Launching lib/main.dart in debug mode...
...
Installing and launching...
Oops; flutter has exited unexpectedly: "SocketException: Send failed (OS Error: No route to host, errno = 65), address = 0.0.0.0, port = 5353".

解釋和建議

此問題與 macOS 許可權有關。

要解決此問題

1. 將您的 Flutter SDK 升級到最新版本。

2. 開啟 System Settings > Privacy & Security > Local Network。為您用於啟動 Flutter 應用程式的所有程式碼編輯器和終端啟用許可權。您可能需要重新啟動您的程式碼編輯器、終端和物理裝置。

此問題表現為何？

執行 flutter 命令會產生“退出程式碼：69”錯誤，如下例所示

Running "flutter pub get" in flutter_tools...
Resolving dependencies in .../flutter/packages/flutter_tools... (28.0s)
Got TLS error trying to find package test at https://pub.dev/.
pub get failed
command:
".../flutter/bin/cache/dart-sdk/bin/
dart __deprecated_pub --color --directory
.../flutter/packages/flutter_tools get --example"
pub env: {
  "FLUTTER_ROOT": ".../flutter",
  "PUB_ENVIRONMENT": "flutter_cli:get",
  "PUB_CACHE": ".../.pub-cache",
}
exit code: 69

解釋和建議

此問題與網路有關。嘗試以下說明進行故障排除

• 檢查您的網際網路連線。確保您已連線到網際網路並且連線穩定。
• 重新啟動您的裝置，包括您的計算機和網路裝置。
• 使用 VPN 有助於繞過可能阻止您連線到網路的任何限制。
• 如果您已嘗試所有這些步驟，但仍然收到錯誤，請使用 flutter doctor -v 命令列印詳細日誌，並在其中一個社群支援渠道中尋求幫助。

Flutter 社群樂於助人且熱情好客。如果上述建議都無法解決您的安裝問題，請考慮從以下渠道之一尋求支援

• Reddit 上的/r/flutterhelp
• Discord 上的/r/flutterdev，特別是此伺服器上的 install-and-setup 頻道。
• StackOverflow，特別是帶有#flutter 或#dart 標籤的問題。

為了尊重每個人的時間，請在釋出新問題之前搜尋檔案中是否有類似問題。