安装问题排查

本页介绍一些新 Flutter 用户遇到的常见安装问题，并提供解决建议。

若使用本页后问题仍未解决，可考虑通过 社区支持渠道 中列出的资源寻求帮助。要为本页添加主题或提交更正，你可以在 GitHub 上 提交 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 上，请按照这些 将命令添加到你的 PATH 的说明 操作。

若你已为 Flutter 开发 配置 VS Code，可以使用 Flutter 扩展的 Locate SDK 提示来定位你的 flutter 文件夹位置。

另请参阅：Configuring PATH and Environment Variables - 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. Run as Administrator: Open your PowerShell terminal as an Administrator.

2. 以管理员身份运行：以管理员身份打开 PowerShell 终端。

3. Check Environment Variables: Ensure the SystemRoot environment variable is set (usually to C:\Windows). You can check its value by running echo $env:SystemRoot in your PowerShell terminal.

4. 检查环境变量：确保已设置 SystemRoot 环境变量（通常为 C:\Windows）。你可以在 PowerShell 终端中运行 echo $env:SystemRoot 来检查其值。

5. Check Execution Policy: If the issue persists, you might need to adjust your execution policy. Run the following command in an Administrator PowerShell window:

6. 检查执行策略：若问题仍然存在，你可能需要调整执行策略。在管理员 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 Development Kit（JDK）时会出现此错误。

若你不需要多个 Java 版本，请从计算机上卸载现有的 JDK。 Flutter 会自动使用 Android Studio 自带的 JDK。

若你确实需要其他 Java 版本，在长期方案实施之前，可尝试 this GitHub issue 中描述的变通方法。更多信息请参阅 Android Java Gradle 迁移指南 或 flutter doctor --android-licenses not working due to 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. 在 Android Studio 中，从菜单栏选择 Tools > SDK Manager 打开 SDK Manager。

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. Upgrade your Flutter SDK to the latest version.

2. 将 Flutter SDK 升级到最新版本。

3. Open System Settings > Privacy & Security > Local Network. Toggle on the permission for all the code editors and terminals you use to launch Flutter apps. You might need to restart your code editor, terminal, and physical device.

4. 打开 System Settings > Privacy & Security > Local Network。为你用于启动 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, in particular, questions tagged with #flutter or #dart.

• StackOverflow，尤其是带有 #flutter 或 #dart 标签的问题。

为尊重每个人的时间，在发布新问题前请先搜索归档中是否有类似问题。