Flutter 桌面端环境搭建与镜像配置

发表于 更新于 分类于
以 Windows 为主：安装 Flutter SDK、PATH、国内镜像与桌面依赖；文末简述 macOS、Linux。

前言

在国内网络环境下开发 Flutter 桌面应用时，除安装 SDK 与桌面构建链外，flutter upgrade、flutter pub get 等也常因访问官方存储与 pub 源较慢而耗时或失败。
下文默认在 Windows 上操作：路径、环境变量与终端命令优先给出 PowerShell 与图形界面步骤。
macOS、Linux 仅在各节末尾作简要对照，便于跨平台读者查阅。
本文按顺序说明前置条件、获取并安装 Flutter SDK、配置 PATH、国内镜像、启用 Windows 桌面目标、Visual Studio 依赖与自检。
下文镜像地址以 Flutter 中文社区常用配置为例。
若你所在网络已能直连官方源，可不必设置镜像。

前置要求

在 Windows 上请先安装 Git for Windows，安装时勾选将 Git 加入 PATH，以便 Flutter 使用。
也可使用 winget install Git.Git 等方式安装，装完后新开终端执行 git --version 验证。

磁盘上建议为 SDK、引擎缓存与工程预留数 GB 以上空间，具体随版本与项目而变。

在首次执行 flutter doctor 或大量拉取依赖之前，可先配置下文镜像变量，通常能减少超时与失败重试。

其它系统： macOS、Linux 同样需安装 Git，并用包管理器或官网安装包完成即可。

安装 SDK

官方常见方式之一是在 Windows 上下载 stable 的 zip，解压到不含空格与特殊字符的路径。
推荐例如 D:\Tools\flutter，勿放在需管理员才能稳定写入的目录，以免后续升级失败。

若使用镜像，宜在解压后、首次运行 flutter 前配置好 PUB_HOSTED_URL 与 FLUTTER_STORAGE_BASE_URL（见下文）。

也可在已安装 Git 的前提下，在 PowerShell 中进入目标父目录后克隆稳定分支（分支名以官网为准，此处为示例）。

下面命令将 Flutter SDK 克隆到 D:\Tools\flutter，请确保 D:\Tools 已存在或先创建该目录。

1
2
cd D:\Tools
git clone https://gitee.com/psvmc/flutter.git -b stable flutter

若你更习惯下载压缩包，请到 Flutter 官网获取 Windows 平台的 stable zip，解压到例如 D:\Tools\flutter 即可。

其它系统： 可将 SDK 放在 ~/development/flutter 等路径，避免空格；解压或 git clone 步骤与 Windows 类似，终端换用 bash 或 zsh 即可。

PATH

将 Flutter 的 bin 目录加入用户或系统的 Path 后，才能在任意「命令提示符」或 PowerShell 中直接执行 flutter。

在 Windows 上打开「系统属性 → 高级 → 环境变量」，在「用户变量」或「系统变量」里选中 Path，点击「编辑」，新建一项并填入你的 flutter\bin 完整路径。
例如 SDK 在 D:\Tools\flutter，则应添加 D:\Tools\flutter\bin。
保存后新开终端，执行 flutter --version 确认能找到命令。

若习惯用命令行写入用户 Path，可在 PowerShell 中读取现有值并追加（请将路径改成你的实际 bin 目录）。

下面示例把 D:\Tools\flutter\bin 追加到当前用户的 Path（若已包含请勿重复添加）。

1
2
3
4
5
$flutterBin = "D:\Tools\flutter\bin"
$old = [Environment]::GetEnvironmentVariable("Path", "User")
if ($old -notlike "*${flutterBin}*") {
  [Environment]::SetEnvironmentVariable("Path", "$old;$flutterBin", "User")
}

其它系统： 向 ~/.zshrc 或 ~/.bashrc 追加 export PATH="$PATH:$HOME/development/flutter/bin"，保存后 source 或重开终端。

镜像变量

Flutter 工具链会从两处拉取资源：一是 Flutter SDK 自身与引擎相关文件（由 FLUTTER_STORAGE_BASE_URL 影响），二是 Dart pub 包仓库（由 PUB_HOSTED_URL 影响）。
将二者同时指向镜像站后，flutter doctor、pub get、升级 SDK 等步骤通常会明显更稳定。

国内常用的社区镜像示例如下（与官方文档中 Flutter 中国社区推荐方式一致，具体以镜像站说明为准）。

临时生效

在 Windows 上若仅需当前 PowerShell 窗口生效，可使用下面写法，随后在同一窗口执行 flutter 相关命令。

下面示例在 PowerShell 当前会话中设置进程环境变量，关闭窗口后即失效。

1
2
$env:PUB_HOSTED_URL = "https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn"

若你使用 Git Bash，可改用与类 Unix 相同的 export 写法。

下面命令在 bash 系终端中为当前会话设置两个变量。

1
2
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

永久生效

在 Windows 上推荐两种方式二选一：图形界面，或 PowerShell 写入用户环境变量。

打开「系统属性 → 高级 → 环境变量」，在「用户变量」中新建 PUB_HOSTED_URL，值为 https://pub.flutter-io.cn；再新建 FLUTTER_STORAGE_BASE_URL，值为 https://storage.flutter-io.cn。
保存后新开终端再运行 flutter。

也可在 PowerShell 中执行下列命令，将两个变量写入当前用户（需 PowerShell 5+）。

下面命令将镜像地址持久化到用户环境，执行完毕后请新开终端。

1
2
[System.Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", "https://pub.flutter-io.cn", "User")
[System.Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", "https://storage.flutter-io.cn", "User")

其它系统： 将两条 export 写入 ~/.bashrc 或 ~/.zshrc，保存后执行 source 或重开终端。

下面给出 shell 配置片段示例（路径与文件名按你使用的 shell 选择其一即可）。

1
2
3
# Flutter 国内镜像（示例：pub 与 SDK 存储）
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

启用桌面

镜像与 PATH 就绪后，需要显式开启桌面支持。
不同 Flutter 版本命令可能略有差异，以 flutter config -h 为准。

在 Windows 上开发桌面应用时，执行下面一条即可打开 Windows 桌面目标。

1
flutter config --enable-windows-desktop

若你还在 macOS、Linux 上编译对应桌面应用，可额外执行下列命令（按实际需要择用）。

1
2
flutter config --enable-macos-desktop
flutter config --enable-linux-desktop

在仅做移动开发的旧习惯环境中，若曾关闭桌面，可用 flutter config 查看当前列表，并按需重新开启。

桌面依赖

flutter doctor 会按平台提示尚缺组件。
在 Windows 上开发桌面应用需安装 Visual Studio（社区版即可），运行 Visual Studio Installer，在工作负载中勾选 使用 C++ 的桌面开发，确保包含 MSVC 与 Windows 10/11 SDK（具体名称以安装器为准）。
安装完成后可重启终端再运行 flutter doctor -v，按提示补装或勾选剩余组件。

其它系统： macOS 需从 App Store 安装 Xcode 并按提示完成许可与组件确认。
Linux 除编译器外通常还需 CMake、Ninja 与 GTK 等开发包，发行版包名略有差异。

下面命令在 Debian、Ubuntu 系上安装常见依赖，供非 Windows 读者参考（若 doctor 仍提示缺项，按其输出补装）。

1
2
sudo apt-get update
sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev

验证

完成 PATH、镜像（若使用）、桌面开关与 Visual Studio 后，在 PowerShell 或「命令提示符」中运行 flutter doctor -v，按提示逐项处理直至 Windows 桌面相关项通过或仅剩可接受警告。

若需快速验证本机 Windows 桌面链路，可在空目录执行下列命令（请将应用名换成你的项目名）。

下面命令创建示例工程并尝试在 Windows 桌面上运行（设备名以 flutter devices 为准）。

1
2
3
4
flutter create my_desktop_app
cd my_desktop_app
flutter pub get
flutter run -d windows

若在 macOS 上验证，最后一行可改为 flutter run -d macos；在 Linux 上可改为 flutter run -d linux。

若 doctor 仍提示无法访问资源，请检查代理、防火墙以及环境变量是否在新终端中已生效。

总结

  1. 在 Windows 上安装 Git，将 Flutter 解压或克隆到如 D:\Tools\flutter，把 flutter\bin 加入用户 Path，再按需设置镜像变量。
  2. 同时设置 PUB_HOSTED_URL 与 FLUTTER_STORAGE_BASE_URL 可分别加速 pub 包与 Flutter 存储访问。
  3. 执行 flutter config --enable-windows-desktop，并安装带 C++ 桌面开发工作负载的 Visual Studio。
  4. 使用 flutter doctor -v 与 flutter run -d windows 完成验证。

若日后需要恢复官方源，在「环境变量」中删除上述两项或改回官方地址即可。