安装故障排除

本页面介绍了 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 标签的问题。

为了尊重他人的时间，请在发布新问题之前搜索存档，看看是否已有类似问题。