内容

每个 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: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs

environment:
  sdk: '>=2.12.0 <3.0.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 个字符——并告诉普通读者他们可能想要了解的有关您的软件包的信息。

将描述视为您的软件包的销售宣传。当用户浏览软件包时,他们会看到它。描述是纯文本:没有标记或 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 参考分开。如果您的软件包有其他文档,请添加一个documentation:字段,其中包含该 URL;pub 会在您的软件包页面上显示指向此文档的链接。

依赖项

#

依赖项是 pubspec 的存在理由。在此部分中,您列出您的软件包工作所需的每个软件包。

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

在开发过程中,您可能需要暂时覆盖依赖项。您可以使用dependency_overrides进行此操作。

有关更多信息,请参阅软件包依赖项

可执行文件

#

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

<name-of-executable>: <Dart-script-from-bin>

例如,以下 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
# This package supports all platforms listed below.
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

以下是一个示例,声明包仅支持 Linux 和 macOS(例如,不支持 Windows)

yaml
# This package supports only Linux and macOS.
platforms:
  linux:
  macos:

publish_to

#

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

yaml
publish_to: none

资金

#

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

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

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

False_secrets

#

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

泄漏检测并不完美。为了避免误报,您可以通过使用 gitignore 模式 在 pubspec 中的 false_secrets 下创建允许列表,告诉 pub 不要在某些文件中搜索泄漏。

例如,以下条目导致 pub 不在文件 lib/src/hardcoded_api_key.darttest/localhost_certificates/ 目录中的所有 .pem 文件中查找泄漏

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

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

屏幕截图

#

软件包可以使用其 pub.dev 页面上显示的屏幕截图来展示其小组件或其他可视元素。要为要显示的软件包指定屏幕截图,请使用 screenshots 字段。

软件包可以在 screenshots 字段下最多列出 10 个屏幕截图。请勿在此部分中包含徽标或其他品牌形象。每个屏幕截图包含一个 description 和一个 pathdescription 解释屏幕截图描述的内容,不超过 160 个字符。例如

yaml
screenshots:
  - description: 'This screenshot shows the transformation of a number of bytes 
  to a human-readable expression.'
    path: path/to/image/in/package/500x500.webp
  - description: 'This screenshot shows a stack trace returning a human-readable
  representation.'
    path: path/to/image/in/package.png

Pub.dev 对屏幕截图的规格限制如下

  • 文件大小:每个图像最大 4 MB。
  • 文件类型:pngjpggifwebp
  • 静态和动画图像均允许。

保持屏幕截图文件较小。每次下载软件包都包含所有屏幕截图文件。

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

主题

#

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

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

yaml
topics:
  - network
  - http

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

  • 最多使用 5 个主题标记每个软件包。
  • 按照以下要求编写主题名称
    • 使用 2 到 32 个字符。
    • 仅使用小写字母数字字符或连字符(a-z0-9-)。
    • 请勿使用两个连续的连字符(--)。
    • 以小写字母字符(a-z)开头。
    • 以字母数字字符(a-z0-9)结尾。

选择主题时,请考虑 现有主题 是否相关。使用现有主题进行标记有助于用户发现您的软件包。

Ignored_advisories

#

如果软件包具有受安全建议影响的依赖项,则 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 has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '^3.0.0'
  
See http://dart.ac.cn/go/sdk-constraint

Flutter SDK 约束

#

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

yaml
environment:
  sdk: '>=1.19.0 <3.0.0'
  flutter: ^0.1.2

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

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