FROM THE BOOKSHELF / A PAGE TO KEEP
技术
79 分钟
Flutter 包开发与插件发布
胡新宇
发布于 2026-05-22
详解Flutter Package与Plugin区别、Federated Plugin架构设计、Platform Interface抽象及pub.dev发布规范

Flutter 包开发与插件发布 (Package & Plugin Development)
模块:模块十 · 架构与工程化
前置知识:Platform Channel、Dart 语言、pub.dev 基础
Package vs Plugin:本质区别
Package(纯 Dart 包) Plugin(含原生代码的包)
┌─────────────────────┐ ┌──────────────────────────────┐
│ Dart 代码 │ │ Dart API 层 │
│ lib/ │ │ lib/ │
│ *.dart │ │ *.dart │
│ test/ │ ├──────────────────────────────┤
│ pubspec.yaml │ │ Android(Kotlin/Java) │
│ │ │ android/ │
│ 例子: │ │ ... │
│ - dio(HTTP) │ ├──────────────────────────────┤
│ - riverpod │ │ iOS(Swift/ObjC) │
│ - freezed │ │ ios/ │
│ - json_serializable│ │ ... │
└─────────────────────┘ ├──────────────────────────────┤
│ macOS / Windows / Linux │
│ macos/ windows/ linux/ │
└──────────────────────────────┘
例子:
- camera(相机)
- geolocator(GPS)
- url_launcher(打开 URL)
Federated Plugin:多平台拆分架构
大型 Plugin 通常采用 Federated Plugin 架构,将不同平台的实现拆分为独立包:
my_camera (用户安装这一个包)
│
├── my_camera_platform_interface (抽象层,定义 Dart 接口)
│ └── CameraPlatform (abstract class)
│
├── my_camera_android (Android 实现)
│ └── CameraAndroid extends CameraPlatform
│
├── my_camera_ios (iOS 实现)
│ └── CameraIOS extends CameraPlatform
│
└── my_camera_web (Web 实现)
└── CameraWeb extends CameraPlatform
优势:
- 平台团队可以独立维护各平台实现
- 用户只引用 App-facing 包,不需要知道哪个包处理哪个平台
- 平台实现可以被第三方替换(如替换 Google Maps 为其他地图)
创建一个 Federated Plugin
第一步:创建包结构
# 创建 App-facing 包(用户直接依赖的)
flutter create --template=plugin my_battery
cd my_battery
# 创建 Platform Interface 包
flutter create --template=package my_battery_platform_interface
# 创建 Android 实现包
flutter create --template=plugin_ffi my_battery_android
# 或(纯 Platform Channel 实现)
flutter create --template=plugin my_battery_android \
--platforms=android
# 创建 iOS 实现包
flutter create --template=plugin my_battery_ios \
--platforms=ios
第二步:Platform Interface 层
// my_battery_platform_interface/lib/my_battery_platform_interface.dart
import 'package:plugin_platform_interface/plugin_platform_interface.dart';
// 使用 plugin_platform_interface 防止非法继承(必须用 implements,不能 extends)
abstract class BatteryPlatform extends PlatformInterface {
BatteryPlatform() : super(token: _token);
// 防止直接 extends(强制使用 implements 或 MockPlatformInterfaceMixin)
static final Object _token = Object();
// 默认实现:抛出未实现错误
static BatteryPlatform _instance = _DefaultBatteryPlatform();
static BatteryPlatform get instance => _instance;
static set instance(BatteryPlatform instance) {
PlatformInterface.verifyToken(instance, _token);
_instance = instance;
}
// 定义平台 API(抽象方法)
Future<int> getBatteryLevel() {
throw UnimplementedError('getBatteryLevel() 未实现');
}
Stream<BatteryState> get onBatteryStateChanged {
throw UnimplementedError('onBatteryStateChanged 未实现');
}
}
// 兜底实现(未安装平台包时使用)
class _DefaultBatteryPlatform extends BatteryPlatform {}
// 状态枚举
enum BatteryState { full, charging, discharging, unknown }
第三步:App-facing 包(API 入口)
// my_battery/lib/my_battery.dart
// 这是用户调用的 API,内部代理到 Platform Interface
import 'package:my_battery_platform_interface/my_battery_platform_interface.dart';
export 'package:my_battery_platform_interface/my_battery_platform_interface.dart'
show BatteryState;
class Battery {
const Battery._();
static const Battery _instance = Battery._();
factory Battery() => _instance;
/// 获取电量百分比(0-100)
Future<int> get batteryLevel => BatteryPlatform.instance.getBatteryLevel();
/// 监听电池状态变化
Stream<BatteryState> get onBatteryStateChanged =>
BatteryPlatform.instance.onBatteryStateChanged;
}
第四步:Android 实现
// my_battery_android/android/src/main/kotlin/com/example/my_battery_android/MyBatteryPlugin.kt
package com.example.my_battery_android
import android.content.Context
import android.content.Intent
import android.content.IntentFilter
import android.os.BatteryManager
import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.plugin.common.EventChannel
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel
class MyBatteryPlugin : FlutterPlugin, MethodChannel.MethodCallHandler {
private lateinit var methodChannel: MethodChannel
private lateinit var eventChannel: EventChannel
private lateinit var context: Context
override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
context = binding.applicationContext
methodChannel = MethodChannel(binding.binaryMessenger, "my_battery_android")
methodChannel.setMethodCallHandler(this)
eventChannel = EventChannel(binding.binaryMessenger, "my_battery_android/events")
eventChannel.setStreamHandler(BatteryStateStreamHandler(context))
}
override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {
when (call.method) {
"getBatteryLevel" -> {
val batteryManager = context.getSystemService(Context.BATTERY_SERVICE) as BatteryManager
val batteryLevel = batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
if (batteryLevel != Int.MIN_VALUE) {
result.success(batteryLevel)
} else {
result.error("UNAVAILABLE", "无法获取电量", null)
}
}
else -> result.notImplemented()
}
}
override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
methodChannel.setMethodCallHandler(null)
}
}
class BatteryStateStreamHandler(private val context: Context) : EventChannel.StreamHandler {
private var broadcastReceiver: android.content.BroadcastReceiver? = null
override fun onListen(arguments: Any?, events: EventChannel.EventSink?) {
broadcastReceiver = object : android.content.BroadcastReceiver() {
override fun onReceive(context: Context?, intent: Intent?) {
val status = intent?.getIntExtra(BatteryManager.EXTRA_STATUS, -1) ?: -1
val state = when (status) {
BatteryManager.BATTERY_STATUS_CHARGING -> "charging"
BatteryManager.BATTERY_STATUS_DISCHARGING -> "discharging"
BatteryManager.BATTERY_STATUS_FULL -> "full"
else -> "unknown"
}
events?.success(state)
}
}
context.registerReceiver(
broadcastReceiver,
IntentFilter(Intent.ACTION_BATTERY_CHANGED)
)
}
override fun onCancel(arguments: Any?) {
context.unregisterReceiver(broadcastReceiver)
broadcastReceiver = null
}
}
// my_battery_android/lib/my_battery_android.dart
// Android 实现:注册到 Platform Interface
import 'package:my_battery_platform_interface/my_battery_platform_interface.dart';
class BatteryAndroid extends BatteryPlatform {
static void registerWith() {
// 注册为默认实现
BatteryPlatform.instance = BatteryAndroid();
}
static const MethodChannel _methodChannel = MethodChannel('my_battery_android');
static const EventChannel _eventChannel = EventChannel('my_battery_android/events');
@override
Future<int> getBatteryLevel() async {
final int level = await _methodChannel.invokeMethod('getBatteryLevel');
return level;
}
@override
Stream<BatteryState> get onBatteryStateChanged {
return _eventChannel.receiveBroadcastStream().map((state) {
return switch (state as String) {
'charging' => BatteryState.charging,
'discharging' => BatteryState.discharging,
'full' => BatteryState.full,
_ => BatteryState.unknown,
};
});
}
}
第五步:iOS 实现
// my_battery_ios/ios/Classes/MyBatteryPlugin.swift
import Flutter
import UIKit
public class MyBatteryPlugin: NSObject, FlutterPlugin {
private var eventSink: FlutterEventSink?
public static func register(with registrar: FlutterPluginRegistrar) {
let methodChannel = FlutterMethodChannel(
name: "my_battery_ios",
binaryMessenger: registrar.messenger()
)
let eventChannel = FlutterEventChannel(
name: "my_battery_ios/events",
binaryMessenger: registrar.messenger()
)
let instance = MyBatteryPlugin()
registrar.addMethodCallDelegate(instance, channel: methodChannel)
eventChannel.setStreamHandler(instance)
}
public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
switch call.method {
case "getBatteryLevel":
UIDevice.current.isBatteryMonitoringEnabled = true
let batteryLevel = UIDevice.current.batteryLevel
if batteryLevel < 0 {
result(FlutterError(code: "UNAVAILABLE", message: "无法获取电量", details: nil))
} else {
result(Int(batteryLevel * 100))
}
default:
result(FlutterMethodNotImplemented)
}
}
}
extension MyBatteryPlugin: FlutterStreamHandler {
public func onListen(
withArguments arguments: Any?,
eventSink events: @escaping FlutterEventSink
) -> FlutterError? {
eventSink = events
UIDevice.current.isBatteryMonitoringEnabled = true
NotificationCenter.default.addObserver(
self,
selector: #selector(batteryStateDidChange),
name: UIDevice.batteryStateDidChangeNotification,
object: nil
)
return nil
}
public func onCancel(withArguments arguments: Any?) -> FlutterError? {
NotificationCenter.default.removeObserver(self)
eventSink = nil
return nil
}
@objc private func batteryStateDidChange() {
let state: String
switch UIDevice.current.batteryState {
case .charging: state = "charging"
case .full: state = "full"
case .unplugged: state = "discharging"
default: state = "unknown"
}
eventSink?(state)
}
}
pubspec.yaml 版本约束语法
# pubspec.yaml 版本约束语法详解
dependencies:
# 精确版本(不推荐,阻止升级)
some_package: 1.2.3
# ^ 约束(推荐):兼容版本
# ^1.2.3 = '>=1.2.3 <2.0.0'(允许 MINOR 和 PATCH 升级)
# ^0.1.2 = '>=0.1.2 <0.2.0'(0.x 版本更严格)
dio: ^5.3.0
# 范围约束
flutter_bloc: '>=8.0.0 <9.0.0'
# 任意版本(危险!不推荐)
some_package: any
# Git 依赖(用于私有包或未发布的版本)
my_private_package:
git:
url: https://github.com/your-org/my_private_package.git
ref: main # branch / tag / commit hash
# 本地路径依赖(开发阶段使用)
my_local_package:
path: ../my_local_package
发布到 pub.dev
发布前检查清单
# Flutter 包开发与插件发布
dart pub publish --dry-run
# 输出示例:
# Package validation found the following potential issues:
# * The description is too short. (minimum 60 characters)
# * README.md is missing.
# * CHANGELOG.md is missing.
# ...
# Flutter 包开发与插件发布
dart pub global activate pana
pana .
pubspec.yaml 完整配置
name: my_battery
description: >
A Flutter plugin to access battery information on Android and iOS.
Provides battery level and battery state stream.
# 至少 60 字符,至多 180 字符
version: 0.1.0 # 首次发布从 0.1.0 开始
homepage: https://github.com/your-org/my_battery
repository: https://github.com/your-org/my_battery
issue_tracker: https://github.com/your-org/my_battery/issues
environment:
sdk: '>=3.0.0 <4.0.0'
flutter: '>=3.10.0'
dependencies:
flutter:
sdk: flutter
my_battery_platform_interface: ^0.1.0
my_battery_android: ^0.1.0
my_battery_ios: ^0.1.0
plugin_platform_interface: ^2.1.0
flutter:
plugin:
platforms:
android:
package: com.example.my_battery_android
pluginClass: MyBatteryPlugin
ios:
pluginClass: MyBatteryPlugin
发布流程
# 1. 登录 pub.dev(Google 账号)
dart pub login
# 2. 运行完整检查
dart pub publish --dry-run
# 3. 确认发布
dart pub publish
# ⚠️ 一旦发布,版本不可删除、不可修改!
# 只能发布新版本或 retract(撤回,用户仍可使用但不再推荐)
pub.dev 评分机制(Pub Points)
满分 160 分,评分维度:
Follow Dart file conventions(30分)
├── pubspec.yaml 格式正确
├── README.md 存在且内容丰富
├── CHANGELOG.md 存在
└── LICENSE 文件存在
Provide documentation(20分)
├── 公共 API 有文档注释
└── 示例代码(example/ 目录)
Platform support(20分)
└── 声明支持的平台(Android/iOS/Web/macOS 等)
Pass static analysis(50分)
├── dart analyze 无错误
└── dart format 格式正确
Support up-to-date dependencies(40分)
└── 依赖包是最新版本
Plugin 最佳实践
错误处理规范
// 统一的错误类型
class BatteryException implements Exception {
const BatteryException(this.message, {this.code});
final String message;
final String? code;
@override
String toString() => 'BatteryException($code): $message';
}
// 在 Platform Interface 中转换 PlatformException
@override
Future<int> getBatteryLevel() async {
try {
return await _methodChannel.invokeMethod<int>('getBatteryLevel') ?? 0;
} on PlatformException catch (e) {
throw BatteryException(
e.message ?? '未知错误',
code: e.code,
);
}
}
API 设计原则
// ✅ 好的 Plugin API 设计
class Battery {
// 工厂构造函数(允许 Mock 和测试)
factory Battery() => Battery._();
const Battery._();
// 属性而非方法(当操作是读取状态时)
Future<int> get batteryLevel => BatteryPlatform.instance.getBatteryLevel();
// Stream 用于持续监听
Stream<BatteryState> get onBatteryStateChanged =>
BatteryPlatform.instance.onBatteryStateChanged;
}
// ❌ 糟糕的 API 设计
class BatteryManager {
// 静态方法无法 Mock
static Future<int> getBatteryLevel() async { ... }
// 不一致的命名
static Stream<int> batteryLevelStream() { ... }
static Future<String> getState() async { ... }
}
过关标准
✅ 能解释 Federated Plugin 的三层结构(platform_interface + 平台实现 + app-facing)的设计意图
✅ 能用 pubspec.yaml 的 ^ 约束语法描述版本兼容范围
✅ 能开发一个支持 Android + iOS 的 Federated Plugin 并发布到 pub.dev
✅ 理解 PlatformInterface.verifyToken 为什么能防止非法继承
✅ 能通过 pana 工具检查并优化包的 pub.dev 评分
全系列总结
至此,Flutter 深度学习系列 32 篇全部完成,覆盖内容:
| 模块 | 文章编号 | 核心主题 |
|---|---|---|
| Dart 语言 | 01-05 | 类型系统、异步、泛型、Dart 3 |
| Widget 体系 | 06-08 | 三棵树、生命周期、组合模式 |
| 布局渲染 | 09-11 | 约束模型、自定义绘制、Sliver |
| 状态管理 | 12-14 | InheritedWidget、方案对比、Riverpod |
| 导航路由 | 15-16 | Navigator 1.0/2.0、go_router |
| 动画系统 | 17-19 | 隐式/显式动画、物理动画、页面转场 |
| 网络数据 | 20-22 | HTTP、本地存储、Isolate |
| 平台集成 | 23-25 | Platform Channel、FFI、多端适配 |
| 性能优化 | 26-28 | 渲染分析、内存管理、编译优化 |
| 架构工程 | 29-32 | Clean Architecture、测试、CI/CD、Plugin |
系列完结 🎉