目录

pubspec 文件

目录 keyboard_arrow_down keyboard_arrow_up
more_horiz

每个 pub 包 都需要一些元数据来指定其 依赖项 。与他人共享的 Pub 包还需要提供其他一些信息，以便用户可以发现它们。所有这些元数据都位于包的_pubspec_中：一个名为 pubspec.yaml 的文件，它使用 YAML 语言编写。

支持的字段

#

pubspec 可以包含以下字段：

name
每个包都需要。 了解更多
version
对于托管在 pub.dev 站点上的包是必需的。 了解更多
description
对于托管在 pub.dev 站点上的包是必需的。 了解更多
homepage
可选。指向包的主页（或源代码存储库）的 URL。 了解更多
repository
可选。指向包的源代码存储库的 URL。 了解更多
issue_tracker
可选。指向包的问题跟踪器的 URL。 了解更多
documentation
可选。指向包的文档的 URL。 了解更多
dependencies
如果您的包没有依赖项，可以省略。 了解更多
dev_dependencies
如果您的包没有开发依赖项，可以省略。 了解更多
dependency_overrides
如果您不需要覆盖任何依赖项，可以省略。 了解更多
environment
从 Dart 2 开始是必需的。 了解更多
executables
可选。用于将包的可执行文件放入 PATH 中。 了解更多
platforms
可选。用于在 pub.dev 站点上明确声明支持的平台。 了解更多
publish_to
可选。指定发布包的位置。 了解更多
funding
可选。列出用户可以赞助包开发的 URL。 了解更多
false_secrets
可选。指定在进行预发布搜索以查找潜在的机密泄露时要忽略的文件。 了解更多
screenshots
可选。指定要在 pub.dev 站点 上显示的屏幕截图文件列表。 了解更多
topics
可选。包的主题列表。 了解更多
ignored_advisories
可选。忽略的安全建议列表。 了解更多

Pub 忽略所有其他字段。

如果您添加自定义字段，请为其指定一个不会与未来的 pubspec 字段冲突的唯一名称。例如，不要添加 bugs ，您可以添加一个名为 my_pkg_bugs 的字段。

示例

#

一个简单但完整的 pubspec 看起来像这样：

yaml
name: newtify
description: >-
  你变成蝾螈了吗？你想变成吗？
  这个包可以帮到你。它拥有你一直在寻找的
  所有蝾螈变形功能。
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs

environment:
  sdk: '^3.2.0'

dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0

dev_dependencies:
  test: '>=1.15.0 <2.0.0'

详情

#

本节包含有关每个 pubspec 字段的更多信息。

名称

#

每个包都需要一个名称。这是其他包引用您的包的方式，如果您发布它，它也会向世界显示。

名称应全部小写，使用下划线分隔单词，例如 just_like_this 。仅使用基本的拉丁字母和阿拉伯数字： [a-z0-9_] 。此外，请确保名称是有效的 Dart 标识符——它不能以数字开头，也不能是 保留字 。

尝试选择一个清晰、简洁且未被使用的名称。建议快速搜索 pub.dev 站点 上的包，以确保没有其他包使用您的名称。

版本

#

每个包都有一个版本。版本号对于在 pub.dev 站点上托管您的包是必需的，但对于仅限本地的包可以省略。如果您省略它，您的包的版本隐式为 0.0.0 。

版本控制对于在允许代码快速演变的同时重用代码是必要的。版本号是由点分隔的三个数字，例如 0.2.43 。它还可以选择性地包含构建（ +1 、 +2 、 +hotfix.oopsie ）或预发布（ -dev.4 、 -alpha.12 、 -beta.7 、 -rc.5 ）后缀。

每次发布包时，您都会以特定版本发布它。一旦完成，就认为它是密封的：您无法再修改它。要进行更多更改，您需要一个新版本。

选择版本时，请遵循 语义版本控制 。

描述

#

对于您自己的个人包，这是可选的，但如果您打算发布您的包，则必须提供一个英文描述。描述应相对简短——60 到 180 个字符——并告诉非专业读者他们可能想知道的关于您的包的信息。

将描述视为您包的销售宣传。用户在 浏览包 时会看到它。描述是纯文本：没有 markdown 或 HTML。

主页

#

这应该是指向您包网站的 URL。对于 托管包 ，此 URL 从包的页面链接。虽然提供 homepage 是可选的，但 请提供 它或 repository （或两者）。它有助于用户了解您的包的来源。

存储库

#

可选的 repository 字段应包含您包的源代码存储库的 URL——例如， https://github.com/<user>/<repository> 。如果您将包发布到 pub.dev 站点，则您的包的页面会显示存储库 URL。虽然提供 repository 是可选的，但 请提供 它或 homepage （或两者）。它有助于用户了解您的包的来源。

问题跟踪器

#

可选的 issue_tracker 字段应包含包的问题跟踪器的 URL，可以在其中查看现有错误并提交新错误。pub.dev 站点尝试使用此字段的值显示指向每个包的问题跟踪器的链接。如果缺少 issue_tracker 但存在 repository 并且指向 GitHub，则 pub.dev 站点使用默认的问题跟踪器（ https://github.com/<user>/<repository>/issues ）。

文档

#

一些包有一个单独的主页和 Pub 生成的 API 参考的网站来托管文档。如果您的包有其他文档，请添加一个包含该 URL 的 documentation: 字段；pub 会在您的包的页面上显示指向此文档的链接。

依赖项

#

依赖项 是 pubspec 的 存在的理由 。在本节中，您列出您的包正常工作所需的每个包。

依赖项分为两种类型。 常规依赖项 列在 dependencies: 下——这些是使用您的包的任何人都需要的包。仅在包本身的开发阶段需要的依赖项列在 dev_dependencies 下。

在开发过程中，您可能需要临时覆盖依赖项。您可以使用 dependency_overrides 来做到这一点。

有关更多信息，请参见 包依赖项 。

可执行文件

#

一个包可以将其一个或多个脚本公开为可以直接从命令行运行的可执行文件。要公开一个脚本，请将其列在 executables 字段下。条目列为键/值对：

<可执行文件名称>: <bin目录下的Dart脚本>

例如，以下 pubspec 条目列出了两个脚本：

yaml
executables:
  slidy: main
  fvm:

使用 dart pub global activate 激活包后，键入 slidy 将执行 bin/main.dart 。键入 fvm 将执行 bin/fvm.dart 。如果您没有指定值，则会从键中推断出来。

有关更多信息，请参见 pub global 。

平台

#

当您 发布包 时，pub.dev 会自动检测包支持的平台。如果此平台支持列表不正确，请使用 platforms 明确声明您的包支持哪些平台。

例如，以下 platforms 条目使 pub.dev 将包列为支持 Android、iOS、Linux、macOS、Web 和 Windows：

yaml
# 此包支持以下所有列出的平台。
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

以下是声明包仅支持 Linux 和 macOS（而不是例如 Windows）的示例：

yaml
# 此包仅支持 Linux 和 macOS。
platforms:
  linux:
  macos:

:::note如果您使用 Flutter Flutter 插件的平台支持默认情况下是从 插件声明 派生的。

如果插件声明和实际平台支持之间存在差异，顶级 platforms 声明仍然可以使用，并且在确定平台支持时优先于 Flutter 插件声明。 :::

Publish_to

#

默认使用 pub.dev 站点 。指定 none 以阻止发布包。此设置可用于指定要发布的 自定义 pub 包服务器 。

yaml
publish_to: none

资金

#

包作者可以使用 funding 属性指定一个 URL 列表，这些 URL 提供有关用户如何帮助资助包开发的信息。例如：

yaml
funding:
 - https://www.buymeacoffee.com/example_user
 - https://www.patreon.com/some-account

如果发布到 pub.dev ，则链接会显示在包页面上。这旨在帮助用户资助其依赖项的开发。

False_secrets

#

当您尝试 发布包 时，pub 会搜索潜在的机密凭据、API 密钥或加密密钥泄露。如果 pub 在将要发布的文件中检测到潜在的泄露，则 pub 会警告您并拒绝发布包。

泄漏检测并不完美。为了避免误报，您可以告诉 pub 不要搜索某些文件中的泄露，方法是使用 false_secrets 下的 gitignore 模式 创建一个允许列表。

例如，以下条目导致 pub 不查找文件 lib/src/hardcoded_api_key.dart 和 test/localhost_certificates/ 目录中的所有 .pem 文件中的泄露：

yaml
false_secrets:
 - /lib/src/hardcoded_api_key.dart
 - /test/localhost_certificates/*.pem

用斜杠(/)开头 gitignore 模式确保模式相对于包的根目录。

撤销意外泄露的凭据。 :::

屏幕截图

#

包可以使用在其 pub.dev 页面上显示的屏幕截图来展示其 widget 或其他可视元素。要指定要显示的包的屏幕截图，请使用 screenshots 字段。

一个包可以在 screenshots 字段下列出最多 10 个屏幕截图。不要在此部分中包含徽标或其他品牌图像。每个屏幕截图都包含一个 description 和一个 path 。 description 解释屏幕截图描绘的内容，不超过 160 个字符。例如：

yaml
screenshots:
  - description: '此屏幕截图显示将多个字节转换为人类可读表达式的过程。'
    path: path/to/image/in/package/500x500.webp
  - description: '此屏幕截图显示返回人类可读表示的堆栈跟踪。'
    path: path/to/image/in/package.png

Pub.dev 将屏幕截图限制在以下规范：

  • 文件大小：每张图像最大 4 MB。
  • 文件类型： png 、 jpg 、 gif 或 webp 。
  • 允许静态和动画图像。

保持屏幕截图文件小巧。每个包的下载都包含所有屏幕截图文件。

Pub.dev 从第一个屏幕截图生成包的缩略图图像。如果此屏幕截图使用动画，则 pub.dev 使用其第一帧。

主题

#

包作者可以使用 topics 字段对他们的包进行分类。主题可用于在 pub.dev 上使用过滤器进行搜索时辅助发现。Pub.dev 在包页面和搜索结果中都显示主题。

该字段包含一个名称列表。例如：

yaml
topics:
  - network
  - http

Pub.dev 要求主题遵循以下规范：

  • 使用最多 5 个主题标记每个包。
  • 按照以下要求编写主题名称：
    • 使用 2 到 32 个字符。
    • 仅使用小写字母数字字符或连字符（ a-z 、 0-9 、 - ）。
    • 不要使用两个连续的连字符（ -- ）。
    • 以小写字母字符（ a-z ）开头名称。
    • 以字母数字字符（ a-z 或 0-9 ）结尾。

选择主题时，请考虑 现有主题 是否相关。使用现有主题进行标记可以帮助用户发现您的包。

忽略的建议

#

如果包具有受安全建议影响的依赖项，则 pub 会在依赖项解析期间警告该建议。包作者可以使用 ignored_advisories 字段作为已触发且与包无关的建议的允许列表。

要抑制有关建议的警告，请将建议标识符添加到 ignored_advisories 列表中。例如：

yaml
name: myapp
dependencies:
  foo: ^1.0.0
ignored_advisories:
 - GHSA-4rgh-jx4f-qfcq

有关更多信息，请查看 安全建议 。

SDK 约束

#

包可以指示其支持哪些版本的依赖项，但包还有另一个隐式依赖项：Dart 平台本身。Dart 平台会随着时间的推移而发展，并且包可能仅适用于特定版本的平台。

包可以使用SDK 约束来指定这些版本。此约束位于 pubspec 中单独的顶级 environment 字段内，并使用与依赖项相同的 版本约束 语法。

例如，以下约束表示此包适用于任何版本号为 3.0.0 或更高的 Dart SDK：

yaml
environment:
  sdk: ^3.0.0

Pub 尝试查找其 SDK 约束与您安装的 Dart SDK 版本兼容的包的最新版本。

省略 SDK 约束是一个错误。当 pubspec 没有 SDK 约束时， dart pub get 会失败并显示如下消息：

pubspec.yaml 没有下限 SDK 约束。
您应该编辑 pubspec.yaml 以包含 SDK 约束：

environment:
  sdk: '^3.2.0'

请参见 https://dart.dev/go/sdk-constraint

Flutter SDK 约束

#

Pub 支持在 environment: 字段下指定 Flutter SDK 约束：

yaml
environment:
  sdk: ^3.2.0
  flutter: '>= 3.22.0'

只有当 pub 在 flutter 可执行文件的上下文中运行并且 Flutter SDK 的 version 文件满足版本约束的下限时，才能满足 Flutter SDK 约束。否则，将不会选择该包。

要发布具有 Flutter SDK 约束的包，您必须指定一个 Dart SDK 约束，其最小版本至少为 1.19.0，以确保旧版本的 pub 不会意外安装需要 Flutter 的包。

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.