pubspec 文件
每个 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 字段冲突。例如,您可以添加一个名为 my_pkg_bugs
的字段,而不是 bugs
。
示例
#一个简单但完整的 pubspec 示例如下所示
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: '^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,用户可以在其中查看现有 bug 和提交新 bug。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 条目列出了两个脚本
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
# This package supports all platforms listed below.
platforms:
android:
ios:
linux:
macos:
web:
windows:
这是一个声明包仅支持 Linux 和 macOS(例如,不支持 Windows)的示例
# This package supports only Linux and macOS.
platforms:
linux:
macos:
Publish_to
#默认使用 pub.dev 站点。 指定 none
以阻止包发布。此设置可用于指定自定义 Pub 包服务器进行发布。
publish_to: none
资助
#包作者可以使用 funding
属性指定一个 URL 列表,其中包含用户如何资助包开发的信息。例如
funding:
- https://www.buymeacoffee.com/example_user
- https://www.patreon.com/some-account
如果发布到 pub.dev,这些链接会显示在包页面上。这旨在帮助用户资助其依赖项的开发。
False_secrets
#当您尝试发布包时,pub 会搜索是否存在秘密凭据、API 密钥或加密密钥的潜在泄露。如果 pub 检测到某个将要发布的文件中存在潜在泄露,则 pub 会警告您并拒绝发布该包。
泄露检测并非完美无缺。为了避免误报,您可以通过在 pubspec 的 false_secrets
下使用 gitignore
模式创建允许列表,来告诉 pub 不要在某些文件中搜索泄露。
例如,以下条目导致 pub 不会在文件 lib/src/hardcoded_api_key.dart
以及 test/localhost_certificates/
目录中的所有 .pem
文件中查找泄露。
false_secrets:
- /lib/src/hardcoded_api_key.dart
- /test/localhost_certificates/*.pem
以斜杠(/
)开头 gitignore
模式可确保该模式相对于包的根目录进行考虑。
屏幕截图
#包可以在其 pub.dev 页面上通过显示屏幕截图来展示其小部件或其他视觉元素。要指定包要显示的屏幕截图,请使用 screenshots
字段。
一个包可以在 screenshots
字段下最多列出 10 张屏幕截图。本节中不要包含徽标或其他品牌图像。每张屏幕截图都包含一个 description
和一个 path
。description
以不超过 160 个字符的文字说明屏幕截图所描绘的内容。例如
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。
- 文件类型:
png
、jpg
、gif
或webp
。 - 允许使用静态和动态图像。
请保持屏幕截图文件较小。包的每次下载都包含所有屏幕截图文件。
Pub.dev 从第一张屏幕截图生成包的缩略图。如果此屏幕截图使用动画,pub.dev 会使用其第一帧。
主题
#包作者可以使用 topics
字段对其包进行分类。主题可用于在 pub.dev 上通过过滤器辅助搜索时的可发现性。Pub.dev 会在包页面和搜索结果中显示主题。
该字段由名称列表组成。例如
topics:
- network
- http
Pub.dev 要求主题遵循以下规范
- 每个包最多标记 5 个主题。
- 主题名称应遵循以下要求
- 使用 2 到 32 个字符。
- 只能使用小写字母数字字符或连字符(
a-z
、0-9
、-
)。 - 不要使用两个连续的连字符(
--
)。 - 名称以小写字母字符(
a-z
)开头。 - 以字母数字字符(
a-z
或0-9
)结尾。
在选择主题时,请考虑现有主题是否相关。使用现有主题进行标记有助于用户发现您的包。
Ignored_advisories
#如果一个包有一个受安全公告影响的依赖项,pub 会在依赖解析期间警告该公告。包作者可以使用 ignored_advisories
字段作为触发的、与该包不相关的公告的允许列表。
要抑制关于某个公告的警告,请将该公告标识符添加到 ignored_advisories
列表中。例如
name: myapp
dependencies:
foo: ^1.0.0
ignored_advisories:
- GHSA-4rgh-jx4f-qfcq
有关更多信息,请查看安全公告。
SDK 约束
#包可以指示它支持其依赖项的哪些版本,但包还有另一个隐式依赖:Dart 平台本身。Dart 平台会随着时间演进,一个包可能只适用于特定版本的平台。
包可以使用 SDK 约束来指定这些版本。此约束位于 pubspec 中一个单独的顶层 environment
字段内,并使用与依赖项相同的版本约束语法。
例如,以下约束表示此包适用于版本 3.0.0 或更高版本的任何 Dart SDK
environment:
sdk: ^3.0.0
Pub 会尝试查找与您已安装的 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
Flutter SDK 约束
#Pub 支持在 environment:
字段下指定 Flutter SDK 约束
environment:
sdk: ^3.2.0
flutter: '>=3.22.0'
只有当 pub 在 flutter
可执行文件的上下文中运行,并且 Flutter SDK 的 version
文件满足版本约束的下限时,Flutter SDK 约束才会被满足。否则,将不会选择该包。
要发布带有 Flutter SDK 约束的包,您必须指定一个最低版本为 1.19.0 或更高的 Dart SDK 约束,以确保旧版本的 pub 不会意外安装需要 Flutter 的包。