Flutter 3.44 配合 Dart 3.12 引入了多项重要变更——withValues 替代 withOpacity、Swift Package Manager 成为 iOS 默认、AGP 9.0 + Kotlin 2.3 等。本文整理一套可落地的开发规范体系，涵盖技能分级、项目模板、代码约束和 AI 辅助配置，适用于团队协作项目。

一、Flutter 3.44 环境概览

维度 版本
Flutter 3.44.4
Dart 3.12.2
AGP 9.0.1
Kotlin 2.3.20
Gradle 9.1.0
Java 17
iOS 最低版本 12.0
AndroidX ✅ 已启用
iOS 依赖管理 Swift Package Manager（无 Podfile）

💡 从 Flutter 3.22+ 开始，新项目默认使用 Swift Package Manager 而非 CocoaPods 管理 iOS 依赖。Podfile 和 ios/Pods/ 不再需要，.gitignore 中对应条目仍然保留用于旧项目迁移兼容。

二、技能分级体系（Skills）

基于 flutter/skills 官方仓库，建立三级技能体系，统一 AI 辅助开发标准：

层级总览

1
2
3
L1 通用技能  ← flutter/skills（官方，首选）
L2 专项技能  ← CPF-Flutter/skills（鸿蒙适配，按需）
L3 定制技能  ← 团队自建 Rules + Skills（强制约束）

选择策略

项目类型 L1 官方 L2 鸿蒙 L3 定制 说明
纯 iOS/Android ✅ 必须 ❌ 可选 标准 Flutter 项目
鸿蒙跨端 ✅ 必须 ✅ 必须 可选 OpenHarmony 适配
团队协同 ✅ 必须 按需 ✅ 建议 统一架构规范

三、安装 flutter/skills（L1 官方）

安装方式

1
2
3
4
5
# CLI 安装全部技能
npx skills add flutter/skills --skill '*' --agent universal --yes

# 安装指定技能
npx skills add flutter/skills --skill flutter-architecture --agent universal

IDE 用户（如 Cursor）也可将仓库放入 .cursor/skills/ 目录。

推荐技能矩阵

基础架构

技能 强制内容 效果
flutter-architecture Clean Architecture 分层 避免逻辑混杂，View / Domain / Data 三层分离
flutter-setup-declarative-routing GoRouter 声明式路由 统一导航配置，支持深度链接

UI 构建

技能 强制内容 效果
flutter-layout 响应式约束 + 溢出修复 自动检测 Overflowed 报错并修正
flutter-theming Material 3 主题规范 统一 Design Token，避免硬编码色值
flutter-build-responsive-layout 多屏适配模式 Tablet / Desktop / Mobile 三端布局
flutter-add-widget-preview Widget 预览 组件级热重载预览

数据层

技能 强制内容 效果
flutter-http-and-json 类型安全 JSON 序列化 含 Pattern Matching 示例，杜绝 dynamic 蔓延
flutter-state-management 单向数据流规范 Provider / Riverpod / Bloc 统一写法
flutter-implement-json-serialization fromJson/toJson 模板 自动生成序列化代码

测试与优化

技能 强制内容 效果
flutter-testing Widget / 集成测试标准流程 统一测试目录结构 + Mock 策略
flutter-add-widget-test Widget 测试模板 组件级测试覆盖率
flutter-add-integration-test 集成测试流程 端到端场景验证
flutter-performance 16ms 帧预算优化策略 针对 Build / Layout / Paint 各阶段分析

四、团队自定义规范（L3）

当官方技能无法满足团队特定架构时，通过自建 Skills 和 Rules 补充。

机制

1
2
3
4
5
Skills（动态操作指南） + Rules（静态强制约束）
  ↓                        ↓
"怎么做"               "必须遵守什么"
  ↓                        ↓
SKILL.md 定义流程      AGENTS.md / CLAUDE.md 声明规则

项目结构

1
2
3
4
5
6
项目根/
├── AGENTS.md              ← 完整配置 + 技术栈 + 目录结构
├── CLAUDE.md              ← 快速参考 + 硬性约束
├── .agents/skills/        ← 自定义 Skills
│   └── <skill-name>/
│       └── SKILL.md

五、技术栈推荐（Flutter 3.44）

类别 推荐技术 版本参考
状态管理 Riverpod（flutter_riverpod） 2.6.x
路由 GoRouter 14.8.x
HTTP Dio 5.10.x
UI 组件 TDesign Flutter / Material 3 按需
屏幕适配 flutter_screenutil 5.9.x
本地存储 shared_preferences 2.5.x
代码规范 flutter_lints 6.x
加密 dart_sm（SM2）/ pointycastle 按需
图片选择 image_picker 1.1.x
加载动画 flutter_easyloading 3.0.x

🏷️ 选型原则：

  • 状态管理推荐 Riverpod（StateNotifier 模式），比 Provider 更类型安全，比 Bloc 更少样板代码
  • 路由强制 GoRouter 声明式配置，支持深度链接和重定向守卫
  • HTTP 使用 Dio 而非 http 包，拦截器机制更适合业务场景（token 刷新、日志、加密）

六、代码规范

强制规则

约束 说明 来源
状态管理使用 Riverpod（StateNotifier） 架构强制 AGENTS.md
路由使用 GoRouter（声明式） 架构强制 AGENTS.md
颜色透明度使用 .withValues(alpha:) Flutter 3.27+ 废弃 .withOpacity() flutter_lints
文件名使用 lowercase_with_underscores Dart 标准 flutter_lints
BuildContext 跨 async 需检查 mounted 安全规范 AGENTS.md

颜色透明度的迁移

Flutter 3.27+ 已废弃 Color.withOpacity()，应全部替换为：

1
2
3
4
5
// ✅ 新写法
Colors.blue.withValues(alpha: 0.5)

// ❌ 已废弃
Colors.blue.withOpacity(0.5)

💡 withValues(alpha:) 的 alpha 取值范围是 0.0 ~ 1.0，与 withOpacity 一致。

项目结构规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
lib/
├── main.dart                        # 入口
├── global.dart                      # 全局初始化
├── router/                          # 路由
│   └── app_router.dart
├── common/                          # 公共层
│   ├── api/                         # 网络接口
│   ├── models/                      # 数据模型
│   ├── services/                    # 服务层
│   ├── utils/                       # 工具类
│   ├── values/                      # 常量
│   ├── components/                  # 公共组件
│   ├── extension/                   # 扩展方法
│   └── widgets/                     # 通用组件
├── pages/                           # 页面
│   └── <feature>/
│       ├── view.dart                # UI
│       └── widgets/                 # 页面内组件
└── provider/                        # Riverpod Providers
    └── <feature>/

💡 约定：

  • 页面文件：view.dart 放 UI，Provider 放 lib/provider/ 对应目录
  • barrel export：index.dart 中不写 library xxx; 声明
  • 缩进：2 spaces（Dart 标准）

七、Flutter 3.44 的 .gitignore

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# Flutter/Dart/Pub
**/doc/api/
**/ios/Flutter/.last_build_id
.dart_tool/
.config/
.flutter-plugins
.flutter-plugins-dependencies
.pub-cache/
.pub/
/build/

# Platform ephemeral
ios/Flutter/ephemeral/
macos/Flutter/ephemeral/
linux/flutter/ephemeral/
windows/flutter/ephemeral/

# Flutter 3.44+ — iOS SPM generated files
ios/Flutter/Flutter.podspec
ios/Flutter/Generated.xcconfig
ios/Flutter/flutter_export_environment.sh
ios/Flutter/app.flx
ios/Flutter/app.zip

# iOS — auto-generated plugin registrant
ios/Runner/GeneratedPluginRegistrant.h
ios/Runner/GeneratedPluginRegistrant.m

# CocoaPods (legacy projects only)
ios/Pods/
ios/.symlinks/

# Android Studio / Gradle / Kotlin
android/local.properties
android/.gradle/
android/.kotlin/
android/app/src/main/java/
**/android/**/build/
**/android/**/.cxx/

# iOS/macOS — user-specific Xcode data only
**/xcuserdata/

# Flutter version management (FVM)
.fvm/
flutter_sdk/

# Service credentials / secrets
*.keystore
*.jks
*.p8
*.p12
*.key
*.crt
.env
.env.local

# IDE / OS
.DS_Store
*.swp
*.swo
*~

注意：虽然 SPM 已取代 CocoaPods 成为默认方案，但 ios/Pods/ 和 ios/.symlinks/ 仍保留在 .gitignore 中以兼容旧项目迁移。

八、Android 构建配置（AGP 9 + Kotlin DSL）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// android/app/build.gradle.kts
plugins {
    id("com.android.application")
    id("kotlin-android")
}

android {
    namespace = "com.example.app"
    compileSdk = 35

    defaultConfig {
        minSdk = 21
        targetSdk = 35
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}
配置项 推荐值
AGP 9.0.1
Kotlin 2.3.20
Gradle 9.1.0
Java 17
Gradle DSL Kotlin DSL（.kts）
MainActivity Kotlin（.kt）

九、项目初始化检查清单

新项目初始化

  • [ ] flutter create 标准模板
  • [ ] 安装 L1 flutter/skills 全部技能（或按需选装）
  • [ ] 创建 AGENTS.md + CLAUDE.md
  • [ ] 配置 analysis_options.yaml（依赖 flutter_lints 6.x）
  • [ ] 配置 .gitignore（包含 Flutter 3.44+ 新条目）
  • [ ] 初始化 Git

持续维护

  • [ ] flutter analyze 零 error（info/warning 按需清理）
  • [ ] Skills 随 flutter/skills 仓库更新
  • [ ] L3 自定义规则随团队演进迭代
  • [ ] 大版本升级时（如 Flutter 4.0）重新评估技能兼容性

十、参考资源