quickstart fails on Windows with "Flutter SDK not found"

[wang-er-s]

环境信息

• 操作系统: Windows 10
• Flutter 版本: 3.41.4
• Dart 版本: 3.11.1
• Flutter SDK 路径: C:\tools\flutter

问题描述

在 Windows 上，通过 Dart 的 Process.run() 执行 flutter 命令时，默认情况下会失败并抛出 ProcessException: 系统找不到指定的文件。
导致所有需要用到 flutter 命令的地方都会报错找不到 flutter

根本原因

在 Windows 上，Flutter SDK 中的 flutter 文件实际上是一个 Bash 脚本 (#!/usr/bin/env bash)，而不是 Windows 原生的可执行文件。

Flutter SDK 目录结构：

• C:\tools\flutter\bin\flutter - Bash 脚本 (2370 bytes)
• C:\tools\flutter\bin\flutter.bat - Windows 批处理文件 (3080 bytes)

Bash 脚本会在检测到 Windows 环境时自动调用 flutter.bat：

# If we're on Windows, invoke the batch script instead to get proper locking.
if [[ $OS =~ MINGW.* || $OS =~ CYGWIN.* || $OS =~ MSYS.* ]]; then
  exec "${BIN_DIR}/flutter.bat" "$@"
fi

但是，当在 Windows cmd 中直接运行 Bash 脚本时，系统无法识别和执行它。

测试结果

✅ 成功的方法

方式 1: 直接使用 .bat 文件

await Process.run('C:\\tools\\flutter\\bin\\flutter.bat', ['--version']);

方式 2: 使用 runInShell: true

await Process.run('flutter', ['--version'], runInShell: true);

方式 3: 通过 cmd /c 运行

await Process.run('cmd', ['/c', 'flutter', '--version'], runInShell: true);

方式 4: 通过 PowerShell 运行

await Process.run('powershell', ['-Command', 'flutter --version'], runInShell: true);

❌ 失败的方法

直接运行 Bash 脚本

await Process.run('flutter', ['--version']);
// 抛出 ProcessException: 系统找不到指定的文件。

复现步骤

1. 在 Windows 系统上安装 Flutter SDK
2. 创建一个 Dart 脚本：

import 'dart:io';

void main() async {
  // 这会失败
  final result = await Process.run('flutter', ['--version']);
  print(result.stdout);
}

3. 运行脚本：dart test.dart
4. 观察错误：ProcessException: 系统找不到指定的文件。

期望行为

Process.run('flutter', ['--version']) 应该能够成功执行 flutter 命令，就像在终端中直接运行一样。

实际行为

在 Windows 上，由于 flutter 是一个 Bash 脚本，Dart 的进程机制无法直接执行它，导致 ProcessException 异常。