Contents

The pubspec file

每个pub包都需要一些元数据,以便可以指定其依赖项 . 与其他人共享的Pub软件包还需要提供其他信息,以便用户发现它们. 所有这些元数据都放在程序包的pubspec中:YAML语言编写的名为pubspec.yaml的文件.

Supported fields

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上. 学到更多.
publish_to
可选的. 指定在何处发布软件包. 学到更多.

Pub会忽略所有其他字段,

如果添加自定义字段,请为其指定一个唯一名称,该名称不会与将来的pubspec字段冲突. 例如,您可以添加一个名为my_pkg_bugs的字段,而不是添加bugs .

Example

一个简单但完整的pubspec如下所示:

name: newtify
version: 1.2.3
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.
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs
environment:
  sdk: '>=2.0.0 <3.0.0'
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
dev_dependencies:
  test: '>=0.6.0 <0.12.0'

Details

本节包含有关大多数pubspec字段的更多信息.

Name

每个包装都需要一个名称. 这是其他软件包引用您的软件包的方式,以及它在您发布时如何向世界展示的方式.

名称应全部为小写,并带有下划线以分隔单词just_like_this . 仅使用基本的拉丁字母和阿拉伯数字: [a-z0-9_] . 另外,请确保该名称是有效的Dart标识符-它不能以数字开头并且不是保留字 .

尝试选择一个清晰,简洁且尚未使用的名称. 建议在pub.dev站点上快速搜索软件包,以确保没有其他人使用您的名字.

Version

每个软件包都有一个版本. 要在pub.dev站点上托管您的软件包,需要一个版本号,但对于仅本地软件包,可以省略该版本号. 如果您忽略它,则您的软件包的隐式版本为0.0.0 .

版本控制对于重用代码同时使其快速发展十分必要. 版本号是由点分隔的三个数字,例如0.2.43 . 它也可以选择具有build( +1+2+hotfix.oopsie )或预发行版( -dev.4-alpha.12-beta.7-rc.5 )后缀.

Each time you publish your package, you publish it at a specific version. Once that’s been done, consider it hermetically sealed: you can’t touch it anymore. To make more changes, you’ll need a new version.

选择版本时,请遵循语义版本控制.

Description

这对于您自己的个人软件包是可选的,但是如果要发布您的软件包,则必须提供说明,该说明应为英文. 描述应相对简短(60到180个字符),并告诉随便的读者他们可能想知道有关您的包裹的内容.

将描述视为包装的销售宣传. 用户在浏览软件包时会看到它. 描述为纯文本:无markdown或HTML.

Author/authors

不推荐使用. 请改用经过验证的发布者 .

您可能会在旧的pubspecs中看到" author或" authors部分. 这些可选字段是描述软件包作者并提供联系信息的一种方式. 每个作者可以是一个名字( Natalie Weizenbaum ),也可以是一个名字和电子邮件地址( Natalie Weizenbaum <nweiz@google.com> ). 但是,这些值未经验证.

pub.dev站点不再显示软件包作者,并且(从Dart 2.7开始),如果您的pubspec具有" author或" authors部分,则pub publish命令将显示警告.

Homepage

这应该是指向您的包裹网站的URL. 对于托管软件包 ,此URL是从软件包页面链接的. 提供homepage是可选的,但请提供 homepagerepository (或同时提供两者). 它可以帮助用户了解您的包裹的来源.

Repository

The optional repository field should contain the URL for your package’s source code repository — for example, https://github.com/<user>/<repository>. If you publish your package to the pub.dev site, then your package’s page displays the repository URL. While providing a repository is optional, 请提供 it or homepage (or both). It helps users understand where your package is coming from.

Issue tracker

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

Documentation

某些程序包具有一个托管文档的站点,该站点与主页以及与Pub生成的API参考无关. 如果您的软件包中有其他文档,请添加带有该URL的documentation:字段; pub在您的软件包页面上显示此文档的链接.

Dependencies

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

依赖关系属于两种类型之一. 常规依赖项dependencies: -这些是使用您的软件包的任何人也将需要的软件包. 在dev_dependencies下列出了仅在程序包本身的开发阶段所需的依赖dev_dependencies .

在开发过程中,您可能需要临时覆盖依赖项. 您可以使用dependency_overrides .

有关更多信息,请参见包依赖关系 .

Executables

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

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

例如,以下pubspec条目列出了两个脚本:

executables:
  polymer-new-element: new_element
  useful-script:

使用pub global activate软件包后,键入polymer-new-element执行bin/new_element.dart . 键入useful-script执行bin/useful-script.dart . 如果未指定该值,则从键中推断出来.

有关更多信息,请参见pub global .

Publish_to

默认使用pub.dev网站. 不指定none以防止发布程序包. 此设置可用于指定要发布的自定义发布包服务器 .

publish_to: none

SDK constraints

程序包可以指示其支持的依赖项版本,但程序包具有另一个隐式依赖项:Dart平台本身. Dart平台会随着时间的推移而发展,一个程序包可能仅适用于该平台的某些版本.

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

例如,以下约束条件表明此程序包可与任何2.0.0或更高版本的Dart 2 SDK配合使用:

environment:
  sdk: '>=2.0.0 <3.0.0'

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

Flutter SDK constraints

从Dart 1.19.0开始,pub在以下environment:下支持Flutter SDK约束:

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的软件包.

by  ICOPY.SITE