Flutter中.yaml文件内容详解

yaml是什么

YAML（读音/ˈjæməl/），是“Yet Another Markup Language”的英文缩写，翻译过来是：仍是一种标记语言。

因此，yaml就是一种可读性高，用来表达数据序列化的格式，类似于json，但比json格式方便太多了。

YAML最大的特点是巧妙避开了各种封闭符号：如引号、各种括号等，这些符号在嵌套结构时会变得复杂而难以辨别。

yaml中的数据结构

一、对象

对象是键值对的集合，又称字典、映射。

对象的键值对使用冒号结构（key: value）表示，冒号后面要加一个空格。

对象里面可以嵌套对象或者数组，嵌套的时候使用缩进来表示层级关系：

key:
  child-key: value
  child-key2: value2

二、数组

数组是一组按次序排列的值。

以 - 开头的行表示构成一个数组：

  - A
  - B
  - C

数组中可以嵌套数组，嵌套的时候使用缩进来表示层级关系。

三、纯量

纯量是单个的、不可再分的值，比如字符串、布尔、数字、

yaml在Flutter中的实践

一、name

name是当前项目的名称，即包名。必填字段。

这个包名是非常重要的，如果修改了这里的name，那么所有对本地文件的引用中的包名就都需要修改。

二、description

description是当前项目的描述、简介。如果需要将项目托管到pub.dev，则该字段必填，其他情况下非必填。

三、version

version是当前项目的版本号。如果需要将项目托管到pub.dev，则该字段必填，其他情况下非必填。

eg：

version: 1.0.0+1

1.0.0+1 是版本号，其格式是 x.y.z+m ，其中 m 是构建版本。

四、environment

environment是应用或者包的开发环境。

自Dart2.0开始需要添加environment字段，该字段会声明当前项目是基于Dart SDK的哪一个版本进行编译，也就是说，该字段约束了使用dart的版本。

比如：

environment:
  sdk: ">=2.0.0 <3.0.0" # Dart版本约束

约束了当前项目仅适用于2.0~3.0的Dart SDK版本编译。

五、dependencies

dependencies中是项目依赖的其他插件。

在这个标签中列出了保证该项目正常工作所需的每一个软件包及其版本。

（1）直接写明插件名称，并不指定版本

package_name:

此时，如果插件是发布在pub.dev上面，IDE会直接在项目目录下执行flutter packages get来下载该插件的最新版本。

（2）指明具体的版本

package_name: 1.1.0

这样写就约束了插件的版本号是1.1.0，即便后面该插件有了新版本，那么这里的版本号不变的话也还是使用1.1.0版本，不会使用新版本。

有一点需要特别注意，很多人喜欢在插件的版本号前面加一个^，这里面是有坑的。

第一，^符号设计的本意是获取当前大版本下面的最新版本插件，以此来获得最好的支持，比如^1.1.0表示的是可以获取1.x.x的最新版本，但是这里的获取最新版本是建立在之前本地开发环境没有缓存过该插件的前提之下，如果本地开发环境已经缓存过1.x.x的某个版本，那么将会沿用缓存的该版本插件，不会再获取最新版本的插件。这个时候，如果是多人开发的话，那么各个开发人员本地缓存的该插件的版本可能就不一样了，这样就不能保证开发环境的统一了。

第二，1.1.0的三个数字分别叫MAJOR、MINOR、PATCH，根据规则，MAJOR version when you make incompatible API changes, 即：只要MAJOR一致，各版本的API都会兼容，反之则不确定。所以说正常情况下使用^1.1.0是没有问题的，但是我们并不能保证插件开发人员能够做到对插件的版本号的标准化管理，比如该插件有一个大的变动，该变动会导致不能向下版本兼容，此时呢如果插件开发人员将插件的版本号由1.1.0改为1.2.0（按照标准的版本号管理的话，此时应该将版本号改为2.0.0），那么使用^1.1.0来进行版本号管理会导致项目继续使用缓存的1.1.0版本，而不会将版本更新为最新的1.2.0，这个时候如果是多人开发并且另外的开发者是第一次运行，或者是Jenkins打包，那么他们就会使用最新的1.2.0版本，此时由于插件没有做向下兼容，程序就会报错，而在我的电脑上由于使用的还是原来缓存的1.1.0版本的插件，就不会报错，这就有问题了。

综上，指定版本的时候放弃使用^，而是使用具体的版本，这样能够保证程序的可控，有效避免由于插件更新而带来的各种问题。

（3）如果插件不是部署在pub.dev上面，而是部署在自己的服务器上面，那么可以通过URL来指定插件下载的源

  package_name:
    hosted:
    name: package_name
    url: http://some-package-server.com
    version: 1.4.0

其中，url字段对应的是插件下载的源，version字段对应的是该插件的版本信息。

（4）如果插件是发布在git上面

此时可以使用如下方式进行插件获取：

  package_name:
    git:
      url: git://github.com/kean_qi/package_name.git

该方式默认是获取master分支下的代码，如果需要获取其他分支的代码，则要通过ref字段来标明分支信息，如下：

  package_name:
    git:
      url: git://github.com/kean_qi/package_name.git
      ref: some_branch

以上默认是插件存储在项目的根目录下，如果插件存储在项目的某一个子目录中，那么可以通过path字段来指定插件路径：

  package_name:
    git:
      url: git://github.com/kean_qi/package_name.git
      ref: some_branch
      path: path/to/kittens

（5）关于插件的版本version

• 1.1.0 指定特定的版本
• ^1.1.0 上面👆有详细介绍，这里不赘述
• >=1.1.0 插件的最低版本是1.1.0，其功能完全覆盖^1.1.0，并且没有大版本必须为1的限制
• >=1.1.0 <2.0.0 插件最低支持1.1.0，但不得超过2.0.0
• <=1.2.3 插件最高支持到1.2.3

（6）指定Flutter SDK

在dependencies中，还可以指定flutterSDK及其版本：

dependencies:
  flutter:
    sdk: flutter
    version: ">=2.0.0-dev.68.0 <3.0.0"

如果不指定version字段的话，会默认获取FlutterSDK的最新版

（7）依赖本地包

如果我们正在本地开发一个包，包名为pkg1，我们可以通过下面方式进行依赖：

dependencies:
  pkg1:
    path: ../../code/pkg1 

其中，path是你本地项目路径 这里的路径可以是相对的，也可以是绝对的。

六、dev_dependencies

一定要注意区分dependencies和dev_dependencies，前者的依赖包将作为App的代码的一部分参与编译，生成最终的安装包；而后者的依赖包只是作为开发阶段的工具包，主要是为了帮助我们提供开发和测试效率，比如Flutter的自动化测试包等。

七、homepage

homepage是项目的介绍主页，它是一个网址。

八、documentation

documentation是开发文档的位置，是一个网址。

有些package会有一个站点单独承载开发文档，此时就可以将该站点地址填写到documentation字段对应的位置，之后Pub就会在该package的主页上显示指向该文档的链接。

九、repository

repository是项目的源代码远程仓库地址，比如：

https://github.com/<user>/<repository>

如果该项目是开源的package，那么就可以使用repository来配置该库的源代码仓库地址，配置完了之后就可以在Pub上面该package的主页看到对应的仓库链接。

虽然配置homepage或者repository都是可选的，但是我们最好是都提供一下（至少提供其一），因为这样可以帮助用户了解你的包来自何处。

十、issue_tracker

issue_tracker是问题追踪页面。

如果该项目是一个开源且随时更新的项目，那么就可以通过填写该字段，以表明该项目的问题追踪文档站点。如果使用pub.dev来进行项目托管的话，那么pub.dev将尝试通过该字段显示该项目的问题跟踪链接；若该项目托管在github，则可以将该字段填写为github的issues，例如：

issue_tracker: https://github.com/<user>/<repository>/issues

十一、publish_to

将该字段设置为none，可以防止开发人员通过flutter pub publish命令无意间将当前项目发布到pub.dev。

如果当前项目是私人项目，那么一定要加上如下代码：

publish_to: 'none'

如果你想要将项目发布到pub.dev，那么就删除这一行

十二、资源文件的声明配置

可以在flutter字段下配置资源路径、字体等，如下：

flutter:
  uses-material-design: true

  assets:
    - assets/config.env
    - assets/image_assets/bank/
    - assets/image_assets/common/
    - assets/image_assets/common/placeholder/
    - assets/image_assets/goods_detail/
    - assets/image_assets/home/
    - assets/image_assets/login/
    - assets/image_assets/order_check/
    - assets/image_assets/sku_number/

  fonts:
    - family: Schyler
      fonts:
        - asset: fonts/Schyler-Regular.ttf
        - asset: fonts/Schyler-Italic.ttf
          style: italic

关于图片资源的声明，详见如下两篇文章：

• Flutter的图片组件
• 文本、图片和按钮在Flutter中怎么用

以上。