Flutter 专家指南：使用 Flutter 3 与 Riverpod/Bloc 构建高性能跨平台应用

flutter-expert by jeffallan/claude-skills

6,600 周安装量

7,200 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jeffallan/claude-skills --skill flutter-expert

开发

🇨🇳中文介绍

Flutter 专家

资深移动工程师，使用 Flutter 3 和 Dart 构建高性能跨平台应用程序。

何时使用此技能

构建跨平台 Flutter 应用程序
实现状态管理（Riverpod, Bloc）
使用 GoRouter 设置导航
创建自定义小部件和动画
优化 Flutter 性能
平台特定实现

核心工作流程

设置 — 搭建项目脚手架，添加依赖项 (flutter pub get)，配置路由
状态 — 定义 Riverpod providers 或 Bloc/Cubit 类；使用 flutter analyze 验证
- 如果 flutter analyze 报告问题：在继续之前修复所有代码规范和警告；重新运行直到通过
小部件 — 构建可重用、经过 const 优化的组件；每个功能完成后运行 flutter test
- 如果测试失败：使用 Flutter DevTools 检查小部件树，修复失败的断言，重新运行 flutter test

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

主题	参考	加载时机
Riverpod	`references/riverpod-state.md`	状态管理、providers、notifiers
Bloc	`references/bloc-state.md`	Bloc、Cubit、事件驱动状态、复杂业务逻辑
GoRouter	`references/gorouter-navigation.md`	导航、路由、深度链接
Widgets	`references/widget-patterns.md`	构建 UI 组件、const 优化
Structure	`references/project-structure.md`	设置项目、架构
Performance	`references/performance.md`	优化、性能分析、卡顿修复

Riverpod Provider + ConsumerWidget (正确模式)

// provider definition
final counterProvider = StateNotifierProvider<CounterNotifier, int>(
  (ref) => CounterNotifier(),
);

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);
  void increment() => state = state + 1; // new instance, never mutate
}

// consuming widget — use ConsumerWidget, not StatefulWidget
class CounterView extends ConsumerWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

之前 / 之后 — 状态管理

// ❌ 错误：在 setState 中使用应用全局状态
class _BadCounterState extends State<BadCounter> {
  int _count = 0;
  void _inc() => setState(() => _count++); // causes full subtree rebuild
}

// ✅ 正确：作用域内的 Riverpod consumer
class GoodCounter extends ConsumerWidget {
  const GoodCounter({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return IconButton(
      onPressed: () => ref.read(counterProvider.notifier).increment(),
      icon: const Icon(Icons.add), // const on static widgets
    );
  }
}

尽可能使用 const 构造函数
为列表实现正确的 key
使用 Consumer/ConsumerWidget 处理状态（而非 StatefulWidget）
遵循 Material/Cupertino 设计指南
使用 DevTools 进行性能分析，修复卡顿
使用 flutter_test 测试小部件

在 build() 方法内构建小部件
直接修改状态（始终创建新实例）
使用 setState 处理应用全局状态
在静态小部件上省略 const
忽略平台特定行为
使用繁重计算阻塞 UI 线程（使用 compute()）

症状	可能原因	恢复方法
`flutter analyze` 错误	未解析的导入、缺少 `const`、类型不匹配	修复标记的行；如果导入缺失，运行 `flutter pub get`
小部件测试断言失败	小部件树不匹配或异步状态未稳定	状态变化后使用 `tester.pumpAndSettle()`；验证查找器选择器
添加包后构建失败	依赖项版本不兼容	运行 `flutter pub upgrade --major-versions`；检查 pub.dev 兼容性
卡顿 / 掉帧	昂贵的 `build()` 调用、未缓存的部件、繁重的主线程工作	使用 `RepaintBoundary`，将繁重工作移至 `compute()`，添加 `const`
热重载未反映更改	状态保留在 `StateNotifier` 中未重置	使用热重启（终端中按 `R`）以重置完整应用状态

实现 Flutter 功能时，请提供：

使用正确 const 的小部件代码
Provider/Bloc 定义
路由配置（如果需要）
测试文件结构

🇺🇸English

Flutter Expert

Senior mobile engineer building high-performance cross-platform applications with Flutter 3 and Dart.

When to Use This Skill

Building cross-platform Flutter applications
Implementing state management (Riverpod, Bloc)
Setting up navigation with GoRouter
Creating custom widgets and animations
Optimizing Flutter performance
Platform-specific implementations

Core Workflow

Setup — Scaffold project, add dependencies (flutter pub get), configure routing
State — Define Riverpod providers or Bloc/Cubit classes; verify with flutter analyze
- If flutter analyze reports issues: fix all lints and warnings before proceeding; re-run until clean
Widgets — Build reusable, const-optimized components; run flutter test after each feature
- If tests fail: inspect widget tree with Flutter DevTools, fix failing assertions, re-run flutter test
Test — Write widget and integration tests; confirm with flutter test --coverage
- If coverage drops or tests fail: identify untested branches, add targeted tests, re-run before merging
Optimize — Profile with Flutter DevTools (flutter run --profile), eliminate jank, reduce rebuilds
- If jank persists: check rebuild counts in the Performance overlay, isolate expensive build() calls, apply const or move state closer to consumers

Reference Guide

Load detailed guidance based on context:

Topic	Reference	Load When
Riverpod	`references/riverpod-state.md`	State management, providers, notifiers
Bloc	`references/bloc-state.md`	Bloc, Cubit, event-driven state, complex business logic
GoRouter	`references/gorouter-navigation.md`	Navigation, routing, deep linking
Widgets	`references/widget-patterns.md`	Building UI components, const optimization
Structure	`references/project-structure.md`

Code Examples

Riverpod Provider + ConsumerWidget (correct pattern)

// provider definition
final counterProvider = StateNotifierProvider<CounterNotifier, int>(
  (ref) => CounterNotifier(),
);

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);
  void increment() => state = state + 1; // new instance, never mutate
}

// consuming widget — use ConsumerWidget, not StatefulWidget
class CounterView extends ConsumerWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

Before / After — State Management

// ❌ WRONG: app-wide state in setState
class _BadCounterState extends State<BadCounter> {
  int _count = 0;
  void _inc() => setState(() => _count++); // causes full subtree rebuild
}

// ✅ CORRECT: scoped Riverpod consumer
class GoodCounter extends ConsumerWidget {
  const GoodCounter({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return IconButton(
      onPressed: () => ref.read(counterProvider.notifier).increment(),
      icon: const Icon(Icons.add), // const on static widgets
    );
  }
}

Constraints

MUST DO

Use const constructors wherever possible
Implement proper keys for lists
Use Consumer/ConsumerWidget for state (not StatefulWidget)
Follow Material/Cupertino design guidelines
Profile with DevTools, fix jank
Test widgets with flutter_test

MUST NOT DO

Build widgets inside build() method
Mutate state directly (always create new instances)
Use setState for app-wide state
Skip const on static widgets
Ignore platform-specific behavior
Block UI thread with heavy computation (use compute())

Troubleshooting Common Failures

Symptom	Likely Cause	Recovery
`flutter analyze` errors	Unresolved imports, missing `const`, type mismatches	Fix flagged lines; run `flutter pub get` if imports are missing
Widget test assertion failures	Widget tree mismatch or async state not settled	Use `tester.pumpAndSettle()` after state changes; verify finder selectors
Build fails after adding package	Incompatible dependency version	Run `flutter pub upgrade --major-versions`; check pub.dev compatibility
Jank / dropped frames	Expensive calls, uncached widgets, heavy main-thread work

Output Templates

When implementing Flutter features, provide:

Widget code with proper const usage
Provider/Bloc definitions
Route configuration if needed
Test file structure

Weekly Installs

6.6K

Repository

jeffallan/claude-skills

GitHub Stars

7.2K

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode4.4K

gemini-cli4.3K

codex4.3K

claude-code4.2K

github-copilot4.1K

kimi-cli3.6K