pubspec 文件

内容 keyboard_arrow_down keyboard_arrow_up

支持的字段
示例
详情

每个 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 看起来像下面这样

yamlname: 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: '^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 字段下。条目以键/值对的形式列出。

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

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

yamlexecutables:
  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:

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

yaml

publish_to: none

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

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

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

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

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

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

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

gitignore 模式以斜杠 (/) 开头可确保该模式被视为相对于包的根目录。

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

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

yamlscreenshots:
  - 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。
文件类型：png、jpg、gif 或 webp。
静态和动画图像均允许。

保持屏幕截图文件小巧。下载包将包含所有屏幕截图文件。

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

包作者可以使用 topics 字段对包进行分类。主题可用于在 pub.dev 上使用过滤器进行搜索时帮助提高可发现性。Pub.dev 在包页面以及搜索结果中显示主题。

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

yamltopics:
  - network
  - http

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

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

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

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

要禁止有关公告的警告，请将公告标识符添加到 ignored_advisories 列表中。例如：

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

有关更多信息，请查看安全公告。

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

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

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

yamlenvironment:
  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.2.0'
  
See https://dart.ac.cn/go/sdk-constraint

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

yamlenvironment:
  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.5.3。页面上次更新于 2024-10-07。查看源代码或报告问题。

pubspec 文件

支持的字段

示例

详情

名称

版本

描述

主页

存储库

问题跟踪器

文档

依赖项

可执行文件

平台

发布到

资助

虚假密钥

屏幕截图

主题

忽略的公告

SDK 约束

Flutter SDK 约束