← 回到书房大厅Esc

FROM THE BOOKSHELF / A PAGE TO KEEP

技术
79 分钟

Flutter 包开发与插件发布

胡新宇

发布于 2026-05-22

详解Flutter Package与Plugin区别、Federated Plugin架构设计、Platform Interface抽象及pub.dev发布规范

Flutter 包开发与插件发布

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-14InheritedWidget、方案对比、Riverpod
导航路由15-16Navigator 1.0/2.0、go_router
动画系统17-19隐式/显式动画、物理动画、页面转场
网络数据20-22HTTP、本地存储、Isolate
平台集成23-25Platform Channel、FFI、多端适配
性能优化26-28渲染分析、内存管理、编译优化
架构工程29-32Clean Architecture、测试、CI/CD、Plugin

系列完结 🎉