安裝故障排除

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

如果您在閱讀本頁後仍遇到問題，請考慮向 社群支援渠道 中列出的資源求助。若要向本頁新增主題或進行更正，您可以在 GitHub 上 提交問題 (file an issue) 或提交 合併請求 (pull request)。

此問題表現為什麼樣？

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

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

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

解釋與建議

您是否已將 Flutter 新增到您平臺的 PATH 環境變數中？在 Windows 上，請遵循這些 新增命令到路徑的說明。

如果您已經 設定了 VS Code 進行 Flutter 開發，您可以使用 Flutter 外掛的 Locate SDK（定位 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。

此問題表現為什麼樣？

在 Windows 上執行 flutter doctor 時，您可能會看到如下錯誤

Invoke-Expression : You cannot call a method on a null-valued expression.
At ...\update_engine_version.ps1:60 char:20

解釋與建議

此錯誤通常發生於缺少 SystemRoot 環境變數，或者 PowerShell 執行策略阻止了指令碼正常執行。

要解決此問題

1. 以管理員身份執行：以管理員身份開啟 PowerShell 終端。

2. 檢查環境變數：確保設定了 SystemRoot 環境變數（通常為 C:\Windows）。您可以在 PowerShell 終端中執行 echo $env:SystemRoot 來檢查其值。

3. 檢查執行策略：如果問題仍然存在，您可能需要調整執行策略。在管理員許可權的 PowerShell 視窗中執行以下命令

   powershell

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

   content_copy

此問題表現為什麼樣？

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 開發工具包 (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 Manager。請按以下說明操作

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. 開啟 系統設定 > 隱私與安全性 > 區域網。為您用於啟動 Flutter 應用的所有程式碼編輯器和終端開啟許可權。您可能需要重啟程式碼編輯器、終端和物理裝置。

此問題表現為什麼樣？

執行 flutter 命令產生 "exit code: 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 標籤的問題。

為了尊重他人的時間，請在釋出新問題之前搜尋存檔，看看是否已有類似問題。