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 辅助开发标准：

层级总览

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

选择策略

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

---

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

安装方式

1# CLI 安装全部技能
2npx skills add flutter/skills --skill '*' --agent universal --yes
3
4# 安装指定技能
5npx 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 补充。

机制

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

项目结构

1项目根/
2├── AGENTS.md              ← 完整配置 + 技术栈 + 目录结构
3├── CLAUDE.md              ← 快速参考 + 硬性约束
4├── .agents/skills/        ← 自定义 Skills
5│   └── <skill-name>/
6│       └── 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// ✅ 新写法
2Colors.blue.withValues(alpha: 0.5)
3
4// ❌ 已废弃
5Colors.blue.withOpacity(0.5)

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

项目结构规范

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

💡 约定：

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

---

七、Flutter 3.44 的 .gitignore

1# Flutter/Dart/Pub
2**/doc/api/
3**/ios/Flutter/.last_build_id
4.dart_tool/
5.config/
6.flutter-plugins
7.flutter-plugins-dependencies
8.pub-cache/
9.pub/
10/build/
11
12# Platform ephemeral
13ios/Flutter/ephemeral/
14macos/Flutter/ephemeral/
15linux/flutter/ephemeral/
16windows/flutter/ephemeral/
17
18# Flutter 3.44+ — iOS SPM generated files
19ios/Flutter/Flutter.podspec
20ios/Flutter/Generated.xcconfig
21ios/Flutter/flutter_export_environment.sh
22ios/Flutter/app.flx
23ios/Flutter/app.zip
24
25# iOS — auto-generated plugin registrant
26ios/Runner/GeneratedPluginRegistrant.h
27ios/Runner/GeneratedPluginRegistrant.m
28
29# CocoaPods (legacy projects only)
30ios/Pods/
31ios/.symlinks/
32
33# Android Studio / Gradle / Kotlin
34android/local.properties
35android/.gradle/
36android/.kotlin/
37android/app/src/main/java/
38**/android/**/build/
39**/android/**/.cxx/
40
41# iOS/macOS — user-specific Xcode data only
42**/xcuserdata/
43
44# Flutter version management (FVM)
45.fvm/
46flutter_sdk/
47
48# Service credentials / secrets
49*.keystore
50*.jks
51*.p8
52*.p12
53*.key
54*.crt
55.env
56.env.local
57
58# IDE / OS
59.DS_Store
60*.swp
61*.swo
62*~

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

---

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

1// android/app/build.gradle.kts
2plugins {
3    id("com.android.application")
4    id("kotlin-android")
5}
6
7android {
8    namespace = "com.example.app"
9    compileSdk = 35
10
11    defaultConfig {
12        minSdk = 21
13        targetSdk = 35
14    }
15
16    compileOptions {
17        sourceCompatibility = JavaVersion.VERSION_17
18        targetCompatibility = JavaVersion.VERSION_17
19    }
20
21    kotlinOptions {
22        jvmTarget = "17"
23    }
24}

配置项	推荐值
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）重新评估技能兼容性

---

十、参考资源

• flutter/skills 官方仓库 — AI 辅助开发技能集
• Flutter 官方文档
• Dart 3.12 更新日志
• evanca/flutter-ai-rules — 自定义 Rules 参考
• Riverpod 文档
• GoRouter 文档