参考网址

• Flutter 官方文档
• Flutter 官方中文文档
• Flutter 官方中文社区
• 官方仓库

安装

可以参考官网上的 手动安装 Flutter

配置

# 编辑 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/flutter/bin:$PATH"

# 立即生效
source ~/.zshrc  # 或 source ~/.bashrc

运行 flutter doctor

flutter doctor

这会检查并显示需要安装的依赖项。

安装必要的依赖

根据 flutter doctor 提示安装：

• Android Studio（Android 开发）
• Xcode（iOS 开发，仅 macOS）
• VS Code 或 Android Studio IDE

Flutter镜像源设置

因国内访问 https://pub.dev/ 网络不是很稳定，所以还是要设置一下镜像源比较好

永久设置（推荐）

Windows 系统

• 在环境变量中添加：

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

macOS/Linux 系统

编辑 ~/.bashrc、~/.zshrc 或相应shell配置文件：

# Flutter镜像源
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

然后执行：

source ~/.zshrc  # 或 source ~/.bashrc

常用国内镜像源

Flutter 社区在中国大陆维护的官方镜像源（推荐），网站也可以访问，与 pub.dev 官网页面都是一样的：

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

清华大学镜像源：

PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter

上海交大镜像源：

PUB_HOSTED_URL=https://mirror.sjtu.edu.cn/dart-pub
FLUTTER_STORAGE_BASE_URL=https://mirror.sjtu.edu.cn/flutter

腾讯云镜像源：

PUB_HOSTED_URL=https://mirrors.cloud.tencent.com/dart-pub
FLUTTER_STORAGE_BASE_URL=https://mirrors.cloud.tencent.com/flutter

检查镜像是否生效

# 查看环境变量
echo $PUB_HOSTED_URL
echo $FLUTTER_STORAGE_BASE_URL

# 测试下载速度
flutter pub get --verbose

其他优化建议

• 使用 VPN 访问国际网络
• 清理缓存：flutter pub cache clean
• 禁用 IPv6（如果网络支持不好）

恢复默认源

# 删除或注释环境变量中的设置
# 或者临时使用：
unset PUB_HOSTED_URL
unset FLUTTER_STORAGE_BASE_URL

常用命令

项目相关

# 创建新项目
flutter create 项目名称

# 运行项目
flutter run

# 指定设备运行
flutter run -d <device_id>
flutter run -d chrome        # 运行在 Chrome
flutter run -d android       # 运行在 Android 设备
flutter run -d ios           # 运行在 iOS 设备

# 列出所有连接的设备
flutter devices

构建相关

# 调试构建
flutter build apk --debug
flutter build ios --debug

# 发布构建
flutter build apk --release
flutter build ios --release
flutter build appbundle      # Android App Bundle
flutter build ipa            # iOS IPA 文件
flutter build web           # Web 应用

包管理

# 获取 packages
flutter pub get

# 升级 packages
flutter pub upgrade

# 添加依赖
flutter pub add package_name

# 清理并重新获取
flutter clean && flutter pub get

开发工具

# 热重载（运行中按 r）
# 热重启（运行中按 R）

# 分析代码
flutter analyze

# 格式化代码
flutter format .

# 修复 dart 代码格式
dart fix --apply

测试相关

# 运行所有测试
flutter test

# 运行特定测试文件
flutter test test/文件名_test.dart

# 运行测试并生成覆盖率报告
flutter test --coverage

设备与模拟器

# 启动安卓模拟器
flutter emulators --launch <emulator_id>

# 列出可用模拟器
flutter emulators

# 创建新的安卓模拟器
flutter emulators --create [--name xyz]

# 擦除模拟器数据
flutter emulators --wipe-data

升级与维护

# 升级 Flutter
flutter upgrade

# 切换 Flutter 渠道
flutter channel stable     # 稳定版
flutter channel beta       # 测试版
flutter channel dev        # 开发版
flutter channel master     # 主分支

# 查看当前渠道
flutter channel

# 清理构建缓存
flutter clean

插件与包

# 生成插件模板
flutter create --template=plugin 插件名称

# 生成包模板
flutter create --template=package 包名称

# 发布包到 pub.dev
flutter pub publish

国际化

# 生成国际化文件
flutter gen-l10n

# 提取要翻译的字符串
flutter pub run intl_translation:extract_to_arb --output-dir=lib/l10n lib/localization.dart

性能分析

# 性能追踪
flutter run --profile

# 调试模式运行
flutter run --debug

# 显示性能叠加层
flutter run --show-performance-overlay

其他实用命令

# 查看 Flutter 信息
flutter --version
flutter config --list

# 显示帮助
flutter help
flutter <command> --help

# 修复常见问题
flutter doctor -v           # 查看详细诊断信息
flutter doctor --android-licenses  # 接受 Android 许可证

常见问题解决

权限问题（macOS/Linux）

sudo chmod -R 755 flutter/

网络问题（中国用户）

# 设置环境变量
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# Windows PowerShell
$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

清除缓存

flutter precache

推荐配置

VS Code 扩展

• Dart
• Flutter
• Awesome Flutter Snippets
• Pubspec Assist

kDebugMode

kDebugMode 是 Flutter 内置的常量，不需要手动配置。它由 Flutter 框架根据编译模式自动设置。

它定义在 foundation.dart 中：

import 'package:flutter/foundation.dart';

自动判断逻辑

Flutter 根据运行模式自动设置 kDebugMode 的值：

运行模式	kDebugMode 值	说明
flutter run	true	调试模式
flutter run --release	false	发布模式
flutter run --profile	false	性能分析模式
flutter build apk/ios	false	生产构建

使用示例

基本使用

import 'package:flutter/foundation.dart';

MaterialApp(
  debugShowCheckedModeBanner: kDebugMode,  // 只在调试模式显示debug标签
  home: MyHomePage(),
)

调试模式会有一个DEBUG 条带的标识