pubspec.yaml #

概述 #

pubspec.yaml 是 Dart/Flutter 项目的配置文件，定义了包的元数据、依赖、资源等信息。它是 Pub 包管理的核心配置文件。

文件位置 #

text 
my_project/
├── pubspec.yaml      # 项目根目录
├── lib/
├── bin/
└── ...

基本结构 #

yaml 
name: my_package
version: 1.0.0
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。
author: Your Name <your.email@example.com>
homepage: https://example.com
repository: https://github.com/user/repo
issue_tracker: https://github.com/user/repo/issues
documentation: https://docs.example.com

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  http: ^1.0.0
  path: ^1.8.0

dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0

executables:
  my_app: main

必需字段 #

name - 包名 #

包的唯一标识符，必需字段。

yaml 
name: my_package

命名规则 #

  • 只能包含小写字母、数字、下划线和连字符
  • 必须以字母开头
  • 长度不超过 64 个字符
  • 不能使用 Dart 保留字
yaml 
# ✅ 正确
name: my_package
name: my-package
name: mypackage123

# ❌ 错误
name: MyPackage    # 不能有大写字母
name: 123package   # 不能以数字开头
name: my.package   # 不能有点号
name: class        # 不能是保留字

包名命名建议 #

类型 命名风格 示例
库包 小写下划线 http_client
应用包 小写连字符 my-web-app
Flutter 包 小写连字符 flutter_utils
插件包 小写连字符 flutter_plugin_auth

version - 版本号 #

遵循语义化版本控制（SemVer）：MAJOR.MINOR.PATCH

yaml 
version: 1.2.3

版本号规则 #

版本部分 含义 何时增加
MAJOR 主版本 不兼容的 API 变更
MINOR 次版本 向后兼容的功能新增
PATCH 补丁版本 向后兼容的 bug 修复

预发布版本 #

yaml 
version: 1.0.0-alpha.1
version: 1.0.0-beta.2
version: 1.0.0-rc.1

构建元数据 #

yaml 
version: 1.0.0+1
version: 1.0.0+build.123

元数据字段 #

description - 描述 #

包的简短描述，建议不超过 200 个字符。

yaml 
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。

author / authors - 作者 #

yaml 
# 单个作者（已弃用）
author: John Doe <john@example.com>

# 多个作者（推荐）
authors:
  - John Doe <john@example.com>
  - Jane Doe <jane@example.com>

homepage - 主页 #

yaml 
homepage: https://example.com

repository - 代码仓库 #

yaml 
repository: https://github.com/user/repo

issue_tracker - 问题追踪 #

yaml 
issue_tracker: https://github.com/user/repo/issues

documentation - 文档地址 #

yaml 
documentation: https://docs.example.com

license - 许可证 #

yaml 
license: MIT
license: BSD-3-Clause
license: Apache-2.0

环境约束 #

environment - SDK 约束 #

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

版本约束语法 #

约束 含义 示例
any 任意版本（不推荐） any
1.0.0 精确版本 1.0.0
>=1.0.0 大于等于 >=1.0.0
>1.0.0 大于 >1.0.0
<=1.0.0 小于等于 <=1.0.0
<1.0.0 小于 <1.0.0
>=1.0.0 <2.0.0 范围 >=1.0.0 <2.0.0
^1.0.0 兼容版本 ^1.0.0

兼容版本（^）详解 #

yaml 
# ^1.2.3 等价于 >=1.2.3 <2.0.0
# ^0.1.2 等价于 >=0.1.2 <0.2.0
# ^0.0.3 等价于 >=0.0.3 <0.0.4

SDK 版本对应关系 #

Dart SDK Flutter SDK
3.0.0 3.10.0
3.2.0 3.16.0
3.3.0 3.19.0

依赖管理 #

dependencies - 生产依赖 #

运行时需要的依赖：

yaml 
dependencies:
  http: ^1.0.0
  path: ^1.8.0
  crypto: '>=3.0.0 <4.0.0'

dev_dependencies - 开发依赖 #

仅在开发和测试时需要的依赖：

yaml 
dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0
  build_runner: ^2.4.0

dependency_overrides - 依赖覆盖 #

强制使用特定版本：

yaml 
dependency_overrides:
  http: 1.1.0
  path: 1.9.0

依赖来源类型 #

1. pub.dev（默认） #

yaml 
dependencies:
  http: ^1.0.0
  http: ^1.0.0  # 默认从 pub.dev 获取

2. Git 仓库 #

yaml 
dependencies:
  my_package:
    git:
      url: https://github.com/user/repo.git
      ref: main
      path: packages/my_package

3. 本地路径 #

yaml 
dependencies:
  my_package:
    path: ../my_package

4. 私有仓库 #

yaml 
dependencies:
  my_private_package:
    hosted:
      name: my_private_package
      url: https://my-private-repo.com
    version: ^1.0.0

Flutter 特定配置 #

flutter - Flutter 配置 #

yaml 
flutter:
  # 资源配置
  assets:
    - assets/images/
    - assets/config.json

  # 字体配置
  fonts:
    - family: Roboto
      fonts:
        - asset: fonts/Roboto-Regular.ttf
        - asset: fonts/Roboto-Bold.ttf
          weight: 700

  # 插件配置
  plugin:
    platforms:
      android:
        package: com.example.my_plugin
        pluginClass: MyPlugin
      ios:
        pluginClass: MyPlugin
      web:
        pluginClass: MyPlugin
        fileName: my_plugin_web.dart

assets - 资源文件 #

yaml 
flutter:
  assets:
    # 单个文件
    - assets/config.json
    # 整个目录
    - assets/images/
    # 子目录
    - assets/images/icons/

fonts - 字体配置 #

yaml 
flutter:
  fonts:
    - family: Roboto
      fonts:
        - asset: fonts/Roboto-Regular.ttf
        - asset: fontsRoboto-Italic.ttf
          style: italic
        - asset: fonts/Roboto-Bold.ttf
          weight: 700
        - asset: fonts/Roboto-BoldItalic.ttf
          weight: 700
          style: italic

字体属性 #

属性 值
weight 100-900（100=Thin, 400=Normal, 700=Bold）
style normal, italic

plugin - 插件平台配置 #

yaml 
flutter:
  plugin:
    platforms:
      android:
        package: com.example.my_plugin
        pluginClass: MyPlugin
        dartPluginClass: MyPluginDart
      ios:
        pluginClass: MyPlugin
        dartPluginClass: MyPluginDart
      web:
        pluginClass: MyPluginWeb
        fileName: my_plugin_web.dart
      macos:
        pluginClass: MyPluginMacOS
      windows:
        pluginClass: MyPluginWindows
      linux:
        pluginClass: MyPluginLinux

可执行文件 #

executables - 定义命令 #

yaml 
executables:
  my_app: main
  my_tool: tool

运行方式：

bash 
# 全局激活后
dart pub global activate my_package
my_app --help
my_tool --help

平台支持 #

platforms - 声明支持的平台 #

yaml 
platforms:
  android:
  ios:
  web:
  windows:
  macos:
  linux:

主题和截图 #

screenshots - 截图（pub.dev 展示） #

yaml 
screenshots:
  - description: 'Example screenshot'
    path: screenshots/example.png

topics - 主题标签 #

yaml 
topics:
  - http
  - network
  - api

完整示例 #

Dart 库包 #

yaml 
name: my_library
version: 1.0.0
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。
homepage: https://example.com
repository: https://github.com/user/my_library
issue_tracker: https://github.com/user/my_library/issues
documentation: https://docs.example.com
license: MIT

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  http: ^1.0.0
  path: ^1.8.0
  meta: ^1.9.0

dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0
  build_runner: ^2.4.0

executables:
  my_tool:

Dart 应用包 #

yaml 
name: my_app
version: 1.0.0
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  args: ^2.4.0
  http: ^1.0.0

dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0

executables:
  my_app: main

Flutter 库包 #

yaml 
name: my_flutter_package
version: 1.0.0
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。
homepage: https://example.com

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

dependencies:
  flutter:
    sdk: flutter
  provider: ^6.0.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^2.0.0

flutter:
  assets:
    - assets/images/

Flutter 插件包 #

yaml 
name: my_plugin
version: 1.0.0
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。

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

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter

flutter:
  plugin:
    platforms:
      android:
        package: com.example.my_plugin
        pluginClass: MyPlugin
      ios:
        pluginClass: MyPlugin

pubspec.lock 文件 #

概述 #

pubspec.lock 是 Pub 自动生成的文件，记录精确的依赖版本。

文件结构 #

yaml 
packages:
  http:
    dependency: "direct main"
    description:
      name: http
      sha256: "a9db..."
      url: "https://pub.dev"
    source: hosted
    version: "1.1.0"
  path:
    dependency: transitive
    description:
      name: path
      sha256: "087c..."
      url: "https://pub.dev"
    source: hosted
    version: "1.8.3"

是否提交 pubspec.lock #

项目类型 是否提交
应用项目 ✅ 必须提交
库项目 ⚠️ 可选（建议提交）
插件项目 ⚠️ 可选

依赖类型说明 #

类型 描述
direct main 直接生产依赖
direct dev 直接开发依赖
transitive 传递依赖

常见配置错误 #

1. SDK 约束缺失 #

yaml 
# ❌ 错误
name: my_package
version: 1.0.0

# ✅ 正确
name: my_package
version: 1.0.0
environment:
  sdk: '>=3.0.0 <4.0.0'

2. 版本约束过于宽松 #

yaml 
# ❌ 不推荐
dependencies:
  http: any

# ✅ 推荐
dependencies:
  http: ^1.0.0

3. 资源路径错误 #

yaml 
# ❌ 错误（路径不存在）
flutter:
  assets:
    - images/logo.png

# ✅ 正确（确保文件存在）
flutter:
  assets:
    - assets/images/logo.png

4. 字体配置不完整 #

yaml 
# ❌ 错误（缺少 family）
flutter:
  fonts:
    - asset: fonts/Roboto.ttf

# ✅ 正确
flutter:
  fonts:
    - family: Roboto
      fonts:
        - asset: fonts/Roboto.ttf

字段速查表 #

字段 类型 必需 描述
name string ✅ 包名
version string ✅ 版本号
description string ⚠️ 描述（发布时必需）
homepage string ❌ 主页 URL
repository string ❌ 代码仓库 URL
issue_tracker string ❌ 问题追踪 URL
documentation string ❌ 文档 URL
author string ❌ 作者（已弃用）
authors list ❌ 作者列表
license string ❌ 许可证
environment map ✅ SDK 约束
dependencies map ❌ 生产依赖
dev_dependencies map ❌ 开发依赖
dependency_overrides map ❌ 依赖覆盖
executables map ❌ 可执行文件
platforms list ❌ 支持平台
screenshots list ❌ 截图
topics list ❌ 主题标签
flutter map ❌ Flutter 配置

最佳实践 #

1. 始终指定 SDK 约束 #

yaml 
environment:
  sdk: '>=3.0.0 <4.0.0'

2. 使用语义化版本约束 #

yaml 
dependencies:
  http: ^1.0.0    # 推荐
  path: any       # 不推荐

3. 分离生产和开发依赖 #

yaml 
dependencies:
  http: ^1.0.0

dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0

4. 添加必要的元数据 #

yaml 
name: my_package
version: 1.0.0
description: 解析 pubspec.yaml 配置文件，涵盖元数据、依赖管理、资源配置、平台支持等所有字段，正确配置 Dart/Flutter 项目。
homepage: https://example.com
repository: https://github.com/user/repo

5. 使用 flutter create 或 dart create #

bash 
# 让工具生成正确的 pubspec.yaml
dart create my_package
flutter create my_flutter_package

下一步 #

现在你已经深入了解了 pubspec.yaml，接下来学习 依赖管理 掌握更多依赖管理技巧！

最后更新：2026-03-28