Pub 发布包 #

my_package/
├── pubspec.yaml       # 必需
├── README.md          # 必需
├── CHANGELOG.md       # 必需
├── LICENSE            # 必需
├── lib/
│   └── my_package.dart
├── test/
│   └── my_package_test.dart
└── example/
    └── example.dart

name: my_package
version: 1.0.0
description: 的包发布指南，涵盖发布前准备、pubspec 配置、发布流程、版本管理、撤回发布等，成功发布包到 pub.dev。
homepage: https://example.com
repository: https://github.com/user/my_package
issue_tracker: https://github.com/user/my_package/issues
documentation: https://docs.example.com
license: MIT

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  http: ^1.0.0

dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0

# my_package

A clear and concise description of what your package does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Getting started

Add the package to your `pubspec.yaml`:

```yaml
dependencies:
  my_package: ^1.0.0

import 'package:my_package/my_package.dart';

void main() {
  // Example usage
}

### 4. 编写 CHANGELOG.md

记录每个版本的变更：

```markdown
# Changelog

All notable changes to this project will be documented in this file.

## 1.0.0

- Initial release
- Feature 1 added
- Feature 2 added

## 0.2.0

- Breaking change: API refactored
- Feature 3 added

## 0.1.0

- Initial development release

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.

// example/example.dart
import 'package:my_package/my_package.dart';

void main() {
  // Demonstrate package usage
  final result = myFunction();
  print(result);
}

// test/my_package_test.dart
import 'package:test/test.dart';
import 'package:my_package/my_package.dart';

void main() {
  group('MyPackage', () {
    test('should do something', () {
      expect(myFunction(), equals(expectedResult));
    });
  });
}

# 干运行（检查但不发布）
dart pub publish --dry-run

Publishing my_package 1.0.0 to https://pub.dev:
|-- .gitignore
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- analysis_options.yaml
|-- example
|   '-- example.dart
|-- lib
|   |-- my_package.dart
|   '-- src
|       '-- implementation.dart
|-- pubspec.yaml
'-- test
    '-- my_package_test.dart

Total 11 files / 5.2 KB
Package has 0 warnings.

# 登录 Google 账号
dart pub login

# 发布到 pub.dev
dart pub publish

# 跳过确认
dart pub publish --force

# 访问包页面
open https://pub.dev/packages/my_package

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  # PATCH：bug 修复
1.0.1 → 1.1.0  # MINOR：新功能
1.1.0 → 2.0.0  # MAJOR：破坏性变更

# 1. 更新代码
# 编辑文件...

# 2. 更新 CHANGELOG.md
# 添加变更记录

# 3. 更新版本号
# 编辑 pubspec.yaml 中的 version

# 4. 运行测试
dart test

# 5. 干运行
dart pub publish --dry-run

# 6. 发布
dart pub publish

# pubspec.yaml
version: 1.0.0-alpha.1
version: 1.0.0-beta.1
version: 1.0.0-rc.1

dependencies:
  my_package: ^1.0.0-alpha.1  # 需要显式指定

/// A class that does something useful.
///
/// This class provides functionality for...
class MyClass {
  /// Creates a new instance of [MyClass].
  MyClass(this.value);

  /// The value of this instance.
  final int value;

  /// Does something with [value].
  void doSomething() {
    // ...
  }
}

# pubspec.yaml
platforms:
  android:
  ios:
  web:
  windows:
  macos:
  linux:

# analysis_options.yaml
include: package:lints/recommended.yaml

linter:
  rules:
    - avoid_print
    - prefer_single_quotes

# pubspec.yaml
environment:
  sdk: '>=2.17.0 <4.0.0'

// example/example.dart
import 'package:my_package/my_package.dart';

void main() {
  // 完整的示例代码
}

# 撤回特定版本
dart pub unpublish my_package 1.0.0

# 撤回整个包
dart pub unpublish my_package

# 废弃特定版本
dart pub deprecate my_package 1.0.0 "Use 1.1.0 instead"

# 废弃整个包
dart pub deprecate my_package "This package is deprecated. Use other_package instead"

# 发布到私有仓库
dart pub publish --server=https://my-private-repo.com

# 添加认证令牌
dart pub token add https://my-private-repo.com

# 错误信息
Package name already exists

# 解决方案
# 更改包名
name: my_unique_package_name

# 错误信息
Version 1.0.0 already exists

# 解决方案
# 更新版本号
version: 1.0.1

# 错误信息
Package size exceeds limit

# 解决方案
# 使用 .gitignore 排除不必要的文件
# 或使用 .pubignore

# 错误信息
Missing required files

# 解决方案
# 添加 README.md, CHANGELOG.md, LICENSE

# 错误信息
Platform not supported

# 解决方案
# 在 pubspec.yaml 中声明平台
platforms:
  android:
  ios:
  web:

# .github/workflows/publish.yml
name: Publish to pub.dev

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dart-lang/setup-dart@v1
      - name: Install dependencies
        run: dart pub get
      - name: Run tests
        run: dart test
      - name: Publish
        run: dart pub publish --force
        env:
          PUB_TOKEN: ${{ secrets.PUB_TOKEN }}

# melos.yaml
name: my_monorepo

packages:
  - 'packages/*'

scripts:
  publish:
    run: melos exec -- dart pub publish --force

开发阶段：0.x.x
稳定版本：1.x.x
预发布：1.0.0-alpha.1, 1.0.0-beta.1

// 使用 @Deprecated 标记废弃 API
@Deprecated('Use newMethod instead')
void oldMethod() {
  newMethod();
}

void newMethod() {
  // 新实现
}

## 2.0.0

### Breaking changes

- `oldMethod()` has been removed. Use `newMethod()` instead.

### Migration guide

```dart
// Before
oldMethod();

// After
newMethod();

## 包维护

### 定期更新

```bash
# 检查依赖更新
dart pub outdated

# 更新依赖
dart pub upgrade

# 运行测试
dart test

# 发布更新
dart pub publish