Flutter 环境搭建 Dart配置

Windows 系统 Flutter 环境搭建

一、系统前置要求与依赖安装

1. 系统基础要求

系统版本：Windows 10 64位 / Windows 11 64位（不支持32位系统）
磁盘空间：预留至少 2GB 空闲空间，用于存放SDK、编译缓存、依赖包
系统设置：开启系统开发者模式（设置 → 更新和安全 → 开发者选项）

2. 必备环境依赖安装

① 安装 Git 版本工具

Flutter 版本升级、依赖拉取均依赖 Git 环境，必须提前安装。

官网下载：https://git-scm.com/，选择 Windows 版本安装包，默认下一步安装即可，无需修改任何配置。

安装完成后新开终端，输入 git --version 验证是否生效。

② 安装 Visual Studio 编译依赖

Windows 桌面端编译 Flutter 程序必须依赖 Visual Studio 桌面组件，否则 flutter doctor 会持续报错。

下载 Visual Studio Installer ，安装时勾选单个组件：使用 C++ 的桌面开发，无需安装完整IDE，仅保留编译依赖即可。

二、Flutter SDK 下载与安装

严格规避：中文路径、空格路径、特殊字符路径，禁止安装在桌面、中文文件夹、系统C盘用户中文目录。

1. SDK 安装包下载

官网下载 Windows 稳定版压缩包：Flutter 官网 Windows 下载页

2. 解压与目录配置

推荐解压路径：D:\development\flutter

手动创建 D:\development 目录，将解压后的 flutter 文件夹放入该目录，路径全程无中文无空格。

三、系统环境变量配置（核心）

1. 配置 Flutter 全局PATH

右键「此电脑」→ 属性 → 高级系统设置 → 环境变量
在系统变量 列表中找到 Path，点击编辑
新建变量值：D:\development\flutter\bin
一路确定保存所有窗口

2. 配置国内镜像加速

新建两个系统变量，规避Google服务器访问超时问题：

变量名：PUB_HOSTED_URL，变量值：https://pub.flutter-io.cn
变量名：FLUTTER_STORAGE_BASE_URL，变量值：https://storage.flutter-io.cn

四、环境校验与异常问题修复

1. 版本环境校验

必须新开CMD/PowerShell终端，执行命令：

bash 复制代码

flutter --version

正常输出版本号，代表 Flutter + Dart 环境配置成功。

2. 全环境依赖检测

bash 复制代码

flutter doctor

3. 平台专属报错修复方案

① Android 协议未授权

bash 复制代码

flutter doctor --android-licenses

全部输入 y 确认授权。

② Visual Studio 组件缺失

回到上文，安装「使用 C++ 的桌面开发」组件，重启终端重新检测。

③ 终端无法识别 Flutter 命令

环境变量未生效，重启电脑或重新打开终端，核对 bin 路径是否配置正确。

五、开发工具（VS Code）配置

跨平台统一开发工具，轻量高效，适配全系统开发。

下载安装 VS Code：https://code.visualstudio.com/
扩展商店安装两款核心插件：Flutter、Dart
重启 VS Code，自动识别本地 Flutter、Dart 环境，自带代码提示、语法校验、一键运行功能。

macOS 系统 Flutter 环境搭建

一、系统前置要求与依赖安装

1. Xcode 开发环境安装（iOS必备）

前往 App Store 搜索安装 Xcode，安装完成后手动打开一次，完成初始化和组件安装，避免后续编译报错。

仅做 Android / Web / Linux 开发可暂时跳过，完整跨平台开发建议安装。

2. Homebrew 包管理器安装

Homebrew 是 macOS 必备终端工具，用于安装各类依赖环境，打开终端执行以下命令安装：

bash 复制代码

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

M 系列芯片 Mac 安装完成后，按照终端提示执行环境变量配置命令，确保 brew 全局生效。

二、Flutter SDK 下载与安装

提供两种安装方式，新手推荐压缩包安装，简单稳定、无版本冲突。

1. 压缩包安装（新手推荐）

官网下载对应架构的 Flutter 安装包：Flutter 官网 macOS 下载页
- Apple Silicon（M1/M2/M3/M4）：选择 arm64 版本
- Intel 芯片：选择默认 x64 版本
创建专属开发目录（规避中文、空格、特殊字符路径）

bash 复制代码

mkdir -p ~/development

将解压后的 flutter 文件夹移动到上述目录中，最终路径：~/development/flutter

2. Git克隆安装（长期开发推荐）

bash 复制代码

mkdir -p ~/development
cd ~/development
git clone https://github.com/flutter/flutter.git -b stable

三、系统环境变量配置（核心）

首先查看当前终端类型，macOS 10.15+ 默认 zsh 终端

bash 复制代码

echo $SHELL

1. zsh 终端配置（默认主流）

打开环境变量配置文件

bash 复制代码

open ~/.zshrc

若文件不存在，先执行创建命令：touch ~/.zshrc

写入以下配置（包含国内镜像加速，解决下载超时、缓慢问题）

bash 复制代码

# Flutter 全局环境变量
export PATH="$HOME/development/flutter/bin:$PATH"

# 国内 Flutter 镜像加速
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

保存文件，执行命令生效配置

bash 复制代码

source ~/.zshrc

2. bash 终端配置（老旧系统）

bash 复制代码

open ~/.bash_profile

写入相同配置，执行 source ~/.bash_profile 生效

四、环境校验与异常问题修复

1. 版本环境校验

必须新开终端窗口，执行校验命令

bash 复制代码

flutter --version

输出版本信息即代表 Flutter、Dart 环境配置成功。

2. 全环境依赖检测

bash 复制代码

flutter doctor

3. 平台专属报错修复方案

① Xcode 环境异常

bash 复制代码

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
sudo xcodebuild -license

② Android 协议未授权

bash 复制代码

flutter doctor --android-licenses

全部输入 y 确认授权即可。

③ CocoaPods 权限报错（M芯片重点）

禁止使用系统 Ruby，通过 Homebrew 安装新版 Ruby 解决权限问题

bash 复制代码

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
gem install cocoapods

修复完成后，再次执行 flutter doctor，所有项打勾即为环境完全就绪。

五、开发工具（VS Code）配置

与 Windows、Linux 完全一致，轻量高效、调试便捷。

官网下载安装 VS Code：https://code.visualstudio.com/
打开扩展商店，搜索并安装两款核心插件：
- Flutter（官方开发插件）
- Dart（语法支持、代码提示）
安装完成重启 VS Code，自动识别 Flutter 环境。

Linux 系统 Flutter 环境搭建

适配 Ubuntu 20.04/22.04、Debian 11/12 主流发行版，适配 x64、arm64 架构，适配物理机、虚拟机、WSL2 环境。

一、系统前置要求与依赖安装

Linux 编译 Flutter 桌面、Web、安卓项目需提前安装系统依赖，否则会出现编译缺失、权限报错。

bash 复制代码

# 更新软件源
sudo apt update && sudo apt upgrade -y

# 安装Flutter必备系统依赖、编译工具、图形依赖
sudo apt install -y git curl wget unzip cmake gcc clang libgtk-3-dev \
libblkid-dev ninja-build pkg-config libssl-dev

依赖说明：git 用于版本管理、gcc/clang 用于代码编译、libgtk-3-dev 用于 Linux 桌面端界面渲染。

二、Flutter SDK 下载与安装

同样提供两种安装方式，新手推荐压缩包安装，稳定无冲突。

1. 压缩包安装（新手推荐）

官网下载 Linux 对应架构 SDK：Flutter 官网 Linux 下载页
- 普通电脑 x64：选择 linux-x64 版本
- ARM 设备（树莓派、国产ARM主机）：选择 linux-arm64 版本
创建全局开发目录，规避中文、空格路径

bash 复制代码

mkdir -p ~/development
# 解压并移动flutter目录（替换为你下载的压缩包名称）
unzip ~/Downloads/flutter_linux_*.zip -d ~/development/

2. Git克隆安装（长期开发推荐）

bash 复制代码

mkdir -p ~/development
cd ~/development
git clone https://github.com/flutter/flutter.git -b stable

三、系统环境变量配置（核心）

Linux 主流终端分为 bash、zsh，根据自身系统选择配置，默认 Ubuntu 为 bash。

1. bash 终端配置（默认主流）

bash 复制代码

# 编辑环境变量文件
nano ~/.bashrc

文件末尾追加以下内容（PATH+国内镜像）：

bash 复制代码

# Flutter 全局环境变量
export PATH="$HOME/development/flutter/bin:$PATH"

# 国内镜像加速（解决Linux依赖下载超时）
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

保存退出：Ctrl+O 回车、Ctrl+X，生效配置

bash 复制代码

source ~/.bashrc

2. zsh 终端配置（自定义终端）

bash 复制代码

nano ~/.zshrc

写入相同配置，执行 source ~/.zshrc 生效

四、环境校验与异常问题修复

1. 版本环境校验

新开终端执行，验证 Flutter、Dart 环境

bash 复制代码

flutter --version

2. 全环境依赖检测

bash 复制代码

flutter doctor

3. 平台专属报错修复方案

① Android 协议未授权

bash 复制代码

flutter doctor --android-licenses

② 权限不足、编译失败

禁止使用 sudo 运行 flutter 命令，避免权限错乱，若出现缓存权限报错，执行：

bash 复制代码

flutter clean
rm -rf ~/.dart-tool

③ 桌面编译依赖缺失

重新执行前文前置依赖安装命令，补全 gtk、编译工具依赖即可解决。

五、开发工具（VS Code）配置

三平台配置完全一致，适配 Linux 桌面、WSL2 环境。

官网下载 Linux 版 VS Code：https://code.visualstudio.com/，安装 deb 包
扩展商店安装 Flutter、Dart 核心插件
重启 VS Code，自动适配本地 Flutter 开发环境

HelloWorld实战

一、项目创建

bash 复制代码

# 创建项目（名称小写、无中文、无特殊字符）
flutter create flutter_hello_demo

# 进入项目目录
cd flutter_hello_demo

# 用VS Code打开项目
code .

二、HelloWorld完整代码

dart 复制代码

// 导入Flutter核心UI组件库，所有界面开发必备
import 'package:flutter/material.dart';

/// 程序入口函数：Dart/Flutter 程序唯一启动入口
/// void 代表函数无返回值
void main() {
  /// runApp：Flutter顶层核心方法
  /// 作用：将根组件挂载到屏幕，启动整个应用程序
  runApp(const MyHelloApp());
}

/// 自定义应用根组件，继承无状态组件 StatelessWidget
/// StatelessWidget：静态组件，界面数据固定，无需动态更新
class MyHelloApp extends StatelessWidget {
  /// 组件构造函数，super.key 绑定组件唯一标识
  /// const 修饰：编译期常量，优化组件渲染性能
  const MyHelloApp({super.key});

  /// 所有Widget必须重写build方法，用于构建UI界面
  /// BuildContext context：组件上下文，记录组件树层级、位置信息
  @override
  Widget build(BuildContext context) {
    /// MaterialApp：Material设计规范顶层容器
    /// 封装了路由、主题、国际化、调试配置等全局功能
    return MaterialApp(
      // 应用全局标题，多任务后台界面展示
      title: 'Flutter HelloWorld 入门',
      // 关闭右上角debug调试横幅
      debugShowCheckedModeBanner: false,
      // 应用全局主题配置
      theme: ThemeData(
        primarySwatch: Colors.blue, // 全局主色调
      ),
      // 应用默认首页组件
      home: const HomePage(),
    );
  }
}

/// 自定义首页界面组件
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    /// Scaffold：页面骨架组件
    /// 提供导航栏、内容区、底部导航、悬浮按钮等基础页面结构
    return Scaffold(
      // 页面顶部导航栏
      appBar: AppBar(
        title: const Text('Flutter 三平台入门实战'),
      ),
      // 页面主体内容区域
      body: const Center(
        /// Center 居中组件，自动将子组件居中展示
        child: Text(
          // 展示的文本内容
          "Hello World! Flutter 三平台通用",
          // 文本样式自定义
          style: TextStyle(
            fontSize: 28,        // 字体大小
            color: Colors.black87,// 字体颜色
            fontWeight: FontWeight.w600, // 字体粗细
            letterSpacing: 1.2,   // 字间距
          ),
        ),
      ),
    );
  }
}

三、项目运行与打包

bash 复制代码

# 通用运行命令（自动识别设备）
flutter run

# Chrome Web快速调试（三平台通用）
flutter run -d chrome

# 分平台打包命令
flutter build windows --release    # Windows桌面安装包
flutter build macos --release      # macOS桌面安装包
flutter build linux --release      # Linux桌面安装包
flutter build web --release        # 通用Web静态资源包

运行成功后，页面展示居中的 Hello World 文本，代表三平台开发环境搭建完成。

项目结构详解

Plain 复制代码

flutter_hello_demo/
├── lib/                     # 【核心业务代码目录】所有dart业务代码存放此处
│   └── main.dart            # 程序唯一入口文件，整个应用的启动源头
├── android/                 # Android原生工程目录，用于安卓打包、原生交互、权限配置
├── ios/                     # iOS原生工程目录，用于苹果设备打包、Pod依赖、原生配置
├── web/                     # Web端编译资源目录，存放网页打包静态资源
├── windows/                 # Windows桌面端编译配置、打包产物目录
├── macos/                   # Mac桌面端编译配置目录
├── linux/                   # Linux桌面端编译配置、打包产物目录
├── test/                    # 单元测试目录，存放项目自动化测试代码
├── .dart_tool/              # Dart工具缓存目录，存储依赖缓存信息，无需修改
├── build/                   # 项目编译输出目录，存放打包产物、缓存文件，可随时删除
├── pubspec.yaml             # 【项目核心配置文件】管理依赖、资源、版本、权限
├── pubspec.lock             # 自动生成的依赖锁定文件，固定依赖版本，禁止手动修改
└── README.md                # 项目介绍文档

核心配置文件 pubspec.yaml 详解

Plain 复制代码

name: flutter_hello_demo     # 项目包名，全局唯一，禁止大写、中文
description: A new Flutter project. # 项目描述
version: 1.0.0+1             # 项目版本号（前端版本+编译版本）

environment:
  sdk: '>=3.0.0 <4.0.0'      # 项目兼容的Dart SDK版本范围

# 项目运行依赖库（项目运行必须依赖）
dependencies:
  flutter:
    sdk: flutter

# 开发环境依赖（仅开发、测试阶段使用）
dev_dependencies:
  flutter_test:
    sdk: flutter

flutter:
  uses-material-design: true # 启用Material UI组件库
  # assets: 配置图片、JSON、静态资源
  # fonts: 配置自定义字体

Flutter 核心基础概念

一切皆Widget：Flutter 所有界面元素（文字、按钮、布局、页面）都是组件
StatelessWidget 无状态组件：界面数据固定，无需刷新，适用于静态页面（本文示例使用）
StatefulWidget 有状态组件：数据可动态修改，修改后界面自动刷新，适用于交互页面
渲染流程：main入口函数 → runApp挂载根组件 → build构建组件树 → 页面渲染

常用命令与报错解决方案

一、核心命令

bash 复制代码

flutter upgrade      # 升级Flutter SDK到最新稳定版
flutter clean        # 清理项目编译缓存，解决编译报错
flutter pub get      # 拉取项目所有依赖库
flutter devices      # 查看当前可运行的设备
flutter doctor -v    # 查看详细环境检测日志

二、各平台专属问题与解决方案

1. Windows 专属问题

flutter命令无法识别：环境变量未生效，重启终端/电脑，核对bin路径
桌面编译失败：检查Visual Studio C++桌面组件是否安装完整
依赖下载失败：确认国内镜像环境变量配置无误

2. macOS 专属问题

CocoaPods 权限报错：禁止系统Ruby，使用Homebrew安装新版Ruby
模拟器卡顿：M芯片Mac优先使用Chrome Web调试
Xcode 校验失败：执行Xcode环境修复命令，完成授权

3. Linux 专属问题

编译桌面端报错：补全 gtk、cmake、clang 系统依赖
权限异常：禁止sudo执行flutter命令，清理缓存重新编译
终端命令失效：重新source环境变量文件或重启终端

三、通用问题解决方案

依赖下载超时：关闭代理，确认国内镜像配置生效
项目编译报错 ：执行 flutter clean 清理缓存后重新编译