Flutter 插件发布完整指南

发布前准备

1. 完善 pubspec.yaml

name: imin_hardware_plugin
description: iMin hardware plugin for Flutter, supporting printer, scanner, NFC, RFID, scale, and more.
version: 1.0.0
homepage: https://github.com/your-username/imin_hardware_plugin
repository: https://github.com/your-username/imin_hardware_plugin
issue_tracker: https://github.com/your-username/imin_hardware_plugin/issues

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.0.0"

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0

flutter:
  plugin:
    platforms:
      android:
        package: com.imin.hardware
        pluginClass: IminHardwarePlugin

2. 完善 README.md

创建详细的 README.md：

# iMin Hardware Plugin

A Flutter plugin for iMin hardware devices, supporting printer, scanner, NFC, RFID, electronic scale, and more.

## Features

- 🖨️ **Printer**: Print text, images, barcodes, QR codes
- 📷 **Scanner**: Barcode and QR code scanning
- 💳 **NFC**: NFC card reading and writing
- 📡 **RFID**: RFID tag reading
- ⚖️ **Electronic Scale**: Weight measurement and pricing
- 💰 **Cash Drawer**: Cash drawer control
- 📺 **LED Display**: Customer display control
- 🪟 **Floating Window**: Floating window management

## Supported Devices

- iMin D4 series
- iMin M2 series
- iMin Swift series
- Other iMin Android devices

## Installation

Add this to your package's `pubspec.yaml` file:

```yaml
dependencies:
  imin_hardware_plugin: ^1.0.0

Then run:

flutter pub get

Quick Start

Printer Example

import 'package:imin_hardware_plugin/imin_hardware_plugin.dart';

// Initialize printer
await IminPrinter.initPrinter();

// Print text
await IminPrinter.printText("Hello World");

// Print and feed paper
await IminPrinter.printAndFeedPaper(100);

Scanner Example

// Start scanning
IminScanner.startScan();

// Listen to scan results
IminScanner.scanStream.listen((barcode) {
  print('Scanned: $barcode');
});

Electronic Scale Example

// Connect to scale
await IminScaleNew.connectService();

// Start getting weight data
await IminScaleNew.getData();

// Listen to weight events
IminScaleNew.eventStream.listen((event) {
  if (event.isWeight) {
    final data = event.data as ScaleWeightData;
    print('Weight: ${data.net}kg');
  }
});

Documentation

For detailed documentation, see:

Requirements

Flutter SDK: >=3.0.0
Dart SDK: >=3.0.0
Android: minSdkVersion 21

License

MIT License - see LICENSE file for details

Support

📧 Email: support@example.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions


### 3. 创建 CHANGELOG.md

```markdown
# Changelog

## 1.0.0 - 2024-02-02

### Added
- Initial release
- Printer support (text, images, barcodes, QR codes)
- Scanner support (barcode, QR code)
- NFC support (card reading/writing)
- RFID support (tag reading)
- Electronic scale support (weight measurement, pricing)
- Cash drawer control
- LED display control
- Floating window management

### Features
- Complete API documentation
- Example application
- Comprehensive error handling
- Event stream support

### Supported Devices
- iMin D4 series
- iMin M2 series
- iMin Swift series

4. 创建 LICENSE 文件

MIT License

Copyright (c) 2024 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

5. 创建 example 应用

确保 example 目录下有完整的示例应用：

example/
├── lib/
│   ├── main.dart
│   └── pages/
│       ├── printer_page.dart
│       ├── scanner_page.dart
│       ├── nfc_page.dart
│       ├── scale_page.dart
│       └── ...
├── pubspec.yaml
└── README.md

6. 代码质量检查

# 运行代码分析
flutter analyze

# 运行测试
flutter test

# 检查发布准备
flutter pub publish --dry-run

发布到 pub.dev

步骤 1: 注册 pub.dev 账号

访问 https://pub.dev
使用 Google 账号登录
完善个人信息

步骤 2: 验证发布准备

cd FlutterApiTest

# 检查发布准备（不会真正发布）
flutter pub publish --dry-run

检查输出，确保没有错误或警告。

步骤 3: 发布插件

# 正式发布
flutter pub publish

系统会提示：

确认包信息
输入 y 确认
在浏览器中完成 Google 账号验证
等待发布完成

步骤 4: 验证发布

访问 https://pub.dev/packages/imin_hardware_plugin
检查包信息是否正确
查看文档是否正常显示

发布后维护

# 更新版本
# 1. 修改 pubspec.yaml 中的 version
# 2. 更新 CHANGELOG.md
# 3. 重新发布

flutter pub publish

发布到私有仓库

方案 1: 使用 Git 依赖

1. 推送到 Git 仓库

cd FlutterApiTest

# 初始化 Git（如果还没有）
git init

# 添加远程仓库
git remote add origin https://github.com/your-username/imin_hardware_plugin.git

# 提交代码
git add .
git commit -m "Initial commit"
git push -u origin main

# 创建版本标签
git tag v1.0.0
git push origin v1.0.0

2. 在其他项目中使用

dependencies:
  imin_hardware_plugin:
    git:
      url: https://github.com/your-username/imin_hardware_plugin.git
      ref: v1.0.0  # 或者使用 branch: main

方案 2: 使用私有 pub 服务器

1. 搭建私有 pub 服务器

使用 unpub:

# 安装 unpub
dart pub global activate unpub

# 启动服务器
unpub --database mongodb://localhost:27017/dart_pub

2. 配置发布地址

创建 ~/.pub-cache/credentials.json:

{
  "accessToken": "your-access-token",
  "refreshToken": "your-refresh-token",
  "tokenEndpoint": "http://your-server.com/api/oauth/token",
  "scopes": ["openid", "https://pub.dartlang.org/api/scopes/version:create"],
  "expiration": 1234567890000
}

3. 发布到私有服务器

flutter pub publish --server=http://your-server.com

4. 在其他项目中使用

# pubspec.yaml
dependencies:
  imin_hardware_plugin: ^1.0.0

# 配置私有仓库
# 在项目根目录创建 .pub-cache/credentials.json

方案 3: 使用本地路径

dependencies:
  imin_hardware_plugin:
    path: ../imin_hardware_plugin

发布到 GitHub

1. 创建 GitHub 仓库

# 在 GitHub 上创建新仓库
# 然后在本地：

cd FlutterApiTest
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/your-username/imin_hardware_plugin.git
git push -u origin main

2. 创建 Release

# 创建标签
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

在 GitHub 上：

进入仓库页面
点击 "Releases"
点击 "Create a new release"
选择标签 v1.0.0
填写 Release 标题和说明
上传编译好的文件（可选）
点击 "Publish release"

3. 添加 GitHub Actions

创建 .github/workflows/publish.yml:

name: Publish

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: dart-lang/setup-dart@v1
      
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'
      
      - name: Install dependencies
        run: flutter pub get
      
      - name: Analyze
        run: flutter analyze
      
      - name: Run tests
        run: flutter test
      
      - name: Publish to pub.dev
        run: flutter pub publish --force
        env:
          PUB_CREDENTIALS: ${{ secrets.PUB_CREDENTIALS }}

版本管理

语义化版本

遵循 Semantic Versioning:

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  (补丁版本：bug 修复)
1.0.1 → 1.1.0  (次版本：新功能，向后兼容)
1.1.0 → 2.0.0  (主版本：破坏性变更)

版本更新流程

# 1. 修改代码
# 2. 更新版本号
# 编辑 pubspec.yaml
version: 1.0.1

# 3. 更新 CHANGELOG.md
## 1.0.1 - 2024-02-03
### Fixed
- Fixed scale callback issue

# 4. 提交代码
git add .
git commit -m "Release v1.0.1"
git tag v1.0.1
git push origin main
git push origin v1.0.1

# 5. 发布
flutter pub publish

预发布版本

# pubspec.yaml
version: 1.1.0-beta.1

flutter pub publish --dry-run
flutter pub publish

常见问题

Q1: 发布失败：Package validation failed

原因: 代码质量问题或配置错误

解决:

# 运行检查
flutter pub publish --dry-run

# 查看具体错误
flutter analyze

Q2: 发布失败：Authentication failed

原因: 未登录或凭证过期

解决:

# 清除凭证
rm ~/.pub-cache/credentials.json

# 重新发布（会提示登录）
flutter pub publish

Q3: 如何撤回已发布的版本？

答: pub.dev 不支持删除已发布的版本，但可以：

发布新版本修复问题
标记版本为 "discontinued"（联系 pub.dev 支持）

Q4: 如何更新插件文档？

答: 文档会自动从代码注释生成

/// 打印文本
///
/// [text] 要打印的文本内容
/// 
/// 示例:
/// ```dart
/// await IminPrinter.printText("Hello World");
/// ```
Future<void> printText(String text) async {
  // ...
}

Q5: 如何添加示例图片？

在 README.md 中：

## Screenshots

<img src="https://raw.githubusercontent.com/your-username/imin_hardware_plugin/main/screenshots/printer.png" width="300">

Q6: 如何设置最低 Flutter 版本？

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.0.0"

Q7: 如何处理 Android 权限？

在 README.md 中说明：

## Android Setup

Add permissions to `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

发布检查清单

发布前确认：

总结

发布 Flutter 插件的完整流程：

准备阶段
- 完善 pubspec.yaml
- 编写 README.md
- 创建 CHANGELOG.md
- 添加 LICENSE
- 完善示例应用
质量检查
- 运行 flutter analyze
- 运行 flutter test
- 运行 flutter pub publish --dry-run
发布
- 发布到 pub.dev: flutter pub publish
- 或发布到 Git: git push + git tag
- 或发布到私有服务器
维护
- 更新版本号
- 更新 CHANGELOG
- 重新发布

遵循这个指南，你的 Flutter 插件就可以成功发布了！

FilesExpand file tree

PUBLISHING_GUIDE.md

Latest commit

History