安装故障排除

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

如果您在使用本页后仍遇到问题，请考虑向社区支持渠道中列出的任何资源寻求帮助。要向本页添加主题或进行更正，您可以在 GitHub 上提交问题或提交拉取请求。

此问题表现为何种形式？

当您尝试运行 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 提示来识别 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 开发工具包 (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 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. 将您的 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 的问题。

为了尊重所有人的时间，请在发布新问题之前搜索存档以查找类似问题。