pubspec.yaml鸿蒙适配实战：Flutter与ArkTS统一配置元数据桥接方案

做跨端工具链这几年，真正把我反复折腾的其实不是业务逻辑，而是 Flutter 工程里那个不起眼的 pubspec.yaml。一个配置文件，装着工程名称、版本号、SDK 约束、三方依赖、资源清单，CI 打包、代码生成、依赖审计全都围着它转。最近鸿蒙侧也要接入这套配置元数据体系，我不得不把 Dart 生态里专门解析 pubspec.yaml 的三方库 pubspec_yaml 从头到尾拆了一遍，然后做了一次完整的鸿蒙化适配。这篇文章会把适配过程中的路线选择、关键步骤、踩过的坑和最终的 YAML 治理方案全部摊开，适合正在做 Flutter/鸿蒙双端工程，或者想统一多仓库配置口径的团队参考。我不打算写那种“照着抄就能跑”的教程，而是把判断逻辑讲清楚——为什么选这条路、哪些坑值得绕、哪些坑绕不过去只能趟。

1. 为什么 Flutter 和鸿蒙双端团队都被 pubspec.yaml 卡过脖子

1.1 一个容易被低估的事实：pubspec.yaml 是整个 Flutter 工程的活体档案

很多人觉得 pubspec.yaml 就是“列依赖的地方”，真到了要拿它做自动化的时候才发现，这里面的信息密度远超想象。顶层字段有 name、version、description、homepage、repository、issue_tracker、environment，再往下有 dependencies、dev_dependencies、dependency_overrides，还有 flutter 专属段：uses-material-design、assets、fonts、plugins、generate。光是 assets 就能写成嵌套列表，一根路径写错，打包时资源直接找不到。

这个文件承载的其实是工程的“元数据资产”：版本号决定了发布包的语义，environment 里的 sdk 约束决定了可用的 Dart 版本，依赖项决定了许可证审计和漏洞扫描的输入范围。我在某存量工程里做过一次统计，接住它的脚本有 8 个，从版本号自动注入、依赖变更提醒到多仓库对齐，全在文本层各写各的解析逻辑。结果就是同一个文件，5 个脚本读出的字段五花八门：有的把 git 依赖的 ref 当版本号，有的把 sdk 依赖当成普通 hosted 依赖，资产路径又因为 Windows 和 Linux 的分隔符不统一而直接崩掉。

所以如果你打算让鸿蒙侧也参与这套工程治理，第一件事不是写解析器，而是承认一个事实：pubspec.yaml 是一个有结构、有约束、有语义的配置文件，必须用“模型”去接它，而不是用“字符串切片”去猜它。

1.2 跨端存量工程里的三种典型困境

我总结过接入鸿蒙时最常遇到的三种卡点，基本可以覆盖大多数团队的处境。

第一种是存量 Flutter 工程要嵌进鸿蒙壳里跑，但 CI 里原来“dart pub get 之后直接取版本号”的流程全部失效。鸿蒙侧构建要拿 Flutter 模块的版本号去生成包信息，结果只能人肉去 pubspec.yaml 里翻，版本一改就漏。更麻烦的是依赖审计脚本在鸿蒙构建机上没法跑，因为一堆工具链脚本假设了原生 Flutter 环境。

第二种是 ArkTS 原生模块想读 Flutter 侧的依赖清单。典型场景是“关于页面”里展示三方库列表，或者合规巡检要导出一份依赖清单。没有现成库的情况下，大家自然会去写正则。正则能抽 hosted 依赖的“包名: 版本”这种简单形态，一碰到 git 依赖、path 依赖、sdk 依赖就全露馅，更别提 dependency_overrides 和 environment 段了。

第三种是多仓库版本对齐。一个 App 可能有十几个模块仓库，每个仓库都有自己的 pubspec.yaml，版本发布日期分散。要保证各模块之间的版本约束互相兼容，需要把每个仓库的 dependencies 和 environment 拉出来做交叉比对。这时候如果各仓库自己造轮子，字段口径不统一，比对结果一堆误报。

所以问题的本质不是“不会解析 YAML”，而是“缺少一个跨平台、语义完整的 pubspec.yaml 对象模型”。

1.3 为什么偏偏是 pubspec_yaml，而不是手写正则

市面上不是没有 YAML 解析库，Dart 的 yaml 包、Python 的 PyYAML，都能把 YAML 结构读出来。但“能读 YAML”和“能理解 pubspec.yaml”是两回事。

我做过一个对比，下面这张表是给团队做选型时用的：

pubspec_yaml 的价值在于它把 pubspec.yaml 的字段结构固化成了一组强类型模型：Pubspec、DependencyContainer、HostedDependency、GitDependency、PathDependency、SdkDependency、Version、VersionRange。这些模型直接对应 pubspec 文件的语义，而不是单纯的键值对。你拿到一个 Pubspec 对象，就知道 dependencies 里有 hosted、git、path、sdk 四种类型，每种带自己的字段，不会混为一谈。

我当时看到这个库的第一反应是：鸿蒙侧要是能直接复用这套模型，配置治理的工作量能砍掉一大半。问题就变成了——怎么把它弄到鸿蒙工程里去。

2. 动手适配前，先把这个库的内脏摸清楚

2.1 依赖链：pubspec_yaml 背后到底是哪几个包

pubspec_yaml 本身是纯 Dart 实现，它最核心的依赖是 yaml 包。yaml 包是 Dart 生态的 YAML 解析器，负责把 YAML 文本解析成 YamlMap/YamlList，再把序列化写回字符串。再往下，yaml 包依赖了 collection、meta、source_span、string_scanner 这类基础工具包，都是纯 Dart 实现，没有原生代码参与。

这一条依赖链对于鸿蒙化适配来说是个偏好的信号：只要宿主环境里存在可用的 Dart 运行时，这几个包基本都能编译运行，不需要处理原生库交叉编译。真正的难点不在依赖本身，而在依赖获取方式。国内网络环境下直接走 Dart 包仓库拉依赖经常超时，更不用说鸿蒙构建机上还不一定配了 Dart 环境。所以适配的第一步不是改代码，而是把依赖链完整下载下来，做本地化处理。

我建议你把 pubspec_yaml 和它的传递依赖全部源码形式托管到自己的内部仓库，锁死版本号，不要用“最新版”这种浮动的引用方式。原因后面实操部分会细说，这里先记住一个原则：配置元数据这层，稳定大于一切。

2.2 解析与序列化的两段式管道

pubspec_yaml 的工作方式可以拆成两个阶段。

解析阶段：先把 YAML 文本交给 yaml 包的 loadYaml，得到一个动态类型的 YamlMap，然后 pubspec_yaml 自己内部把这棵动态树映射到强类型模型，比如 Pubspec、Dependency 等等。序列化阶段反过来，把模型对象的字段重新聚合成一个普通 Map，再交给 yaml 包输出成 YAML 文本。

这两段式管道意味着一个关键点：YamlMap 是 Map<dynamic, dynamic>，键值都是动态类型。Dart 里有 dynamic 这个概念，写起来很灵活，但到了鸿蒙的 ArkTS 侧，类型系统要严格得多，几乎没有 dynamic，所有字段都要求明确的类型声明。桥接的时候如果不先把动态类型收敛成具体类型，到了 ArkTS 侧就会变成一堆 Any，还得二次解析。

所以适配工作的核心，说白了就是在这条管道的出口处建立一套稳定的、强类型的 JSON 协议，把 Dart 侧的模型语义“翻译”成 ArkTS 能直接消费的数据结构。这一层不做好，后面所有治理逻辑都会建在流沙上。

2.3 版本约束和语义化版本号：最容易踩的隐形坑

如果一个库只解析 name 和 dependencies，那是玩具；pubspec_yaml 真正值钱的部分是它自带版本约束处理。pubspec.yaml 里的 environment.sdk 写的是 >=2.12.0 <3.0.0 这种 VersionRange，dependencies 里的 hosted 依赖也可以带 caret（^1.0.0）或者精确版本。pubspec_yaml 用 Version 和 VersionRange 两个类实现了语义化版本的解析和比较。

这里面的细节非常容易翻车。比如语义化版本的预发布规则：2.0.0-alpha < 2.0.0-beta < 2.0.0；build metadata 不参与优先级比较，2.0.0+build1 和 2.0.0+build2 是同一个优先级。再比如 caret 约束，^1.2.3 的含义是 >=1.2.3 <2.0.0，不是简单的“去掉 ^”就行。

鸿蒙侧最容易踩的坑是自定义版本后缀。有些鸿蒙组件会给自己打上类似 3.1.0-ohos.1 的版本号，这种带自定义 pre-release 后缀的版本，如果解析逻辑没有严格按语义化版本规则处理，约束判断就会出错。之前有同事拿着这种版本号去做依赖冲突检测，直接得出“无法满足约束”的错误结论，排查了半天才发现是版本解析器的预发布规则没实现完整。这也是为什么我强烈建议尽量复用 pubspec_yaml 而不是自己写解析，因为版本比较这个领域，自己写的边界几乎必然有疏漏。

3. 鸿蒙化适配的三条路线，我为什么强烈建议走中间那条

3.1 路线一：直接在鸿蒙的 Flutter 引擎里复用

如果你的鸿蒙应用里本身就嵌了 Flutter 容器，那最简单粗暴的做法就是：把 pubspec_yaml 当成普通 Dart 依赖加进 Flutter 模块，在 Dart 侧解析完，通过通道把结果给到 ArkTS。

这条路线的优点是几乎零适配成本，pubspec_yaml 本来就是 Dart 写的，在 Flutter 容器里跑得顺理成章。缺点也很明显：它只能在 Flutter 模块内部生效。如果 ArkTS 页面或者纯鸿蒙的原生模块想读 pubspec.yaml 的数据，还是得靠桥接。换句话说，这条路只是把问题往后推了半步。

适合的场景是：你已经在鸿蒙 App 里用了 Flutter 做跨端页面，而且配置治理的入口只会在 Dart 侧触发。这种情况就用不着做什么鸿蒙化适配，把依赖加上就行。

3.2 路线二：源码裁剪加桥接开放给 ArkTS（推荐）

我最终采用的是中间这条路线：保留 pubspec_yaml 作为解析引擎，但通过桥接层把能力开放给 ArkTS，让整个鸿蒙工程都能消费同一套配置元数据模型。

具体来说分三步走。第一步，把 pubspec_yaml 和它的依赖链源码本地化，放进鸿蒙工程的第三方组件目录，绕开 Dart 包仓库的网络依赖。第二步，在 Dart 侧封装一个桥接处理器，监听来自 ArkTS 的通道请求，接收 pubspec.yaml 原始文本，返回解析后的 JSON 数据。第三步，在 ArkTS 侧定义对应的强类型接口，把 JSON 结构映射成 interface，后续所有治理逻辑都基于 ArkTS 侧的类型来写。

这条路线最适合团队规模不大、又想让 Flutter 和 ArkTS 共享同一套解析能力的场景。它保留了 pubspec_yaml 的完整语义，包括版本约束比较，同时只付出一个桥接层的开发成本。后面我会把这套做法的实操细节全部放出来。

3.3 路线三：用 ArkTS 完整重写一个等价库

如果你面对的是纯 ArkTS 工程，里面完全没有 Flutter 引擎和 Dart 运行时，但你又确实需要 pubspec.yaml 的解析和治理能力，那就只能考虑重写路线。

重写要处理的不只是 pubspec_yaml 的模型层，还包括底层的 YAML 解析器。方案是找一个 TypeScript/JavaScript 生态的 YAML 解析库，在此基础上重新实现 Pubspec、Dependency、Version 这些模型，以及最重要的语义化版本比较逻辑。这条路的工作量不是“几天的移植”，而是“一个两周以上的小项目”，而且后续上游版本更新时你需要手工同步语义变更。

除非你的团队就是纯 ArkTS 技术栈，完全没有 Dart 环境，否则我不建议走这条路。重写意味着你要把版本比较、依赖类型识别、assets 映射规则这些边界细节全部用测试用例钉死，否则就是给自己埋雷。

3.4 三条路线的横测对比

我的判断逻辑是这样的：如果你的工程既不是纯 Flutter 也不是纯 ArkTS，而是混合形态，那路线二是性价比最高的。它没有放弃 pubspec_yaml 已经打磨成熟的模型能力，又让 ArkTS 侧拿第一手结构化数据，后续不管做依赖审计还是版本对齐，都能站在同一套元数据模型上说话。

4. 实操记录：把 pubspec_yaml 源码搬进鸿蒙工程

4.1 源码获取与依赖本地化

先说源码怎么拿。我当时的操作是开一个临时 Flutter 工程，在 pubspec.yaml 里加上 pubspec_yaml 依赖，执行 dart pub get，然后把缓存目录里对应的 pubspec_yaml、yaml、collection、meta 等包里实际用到的源码目录整体拷出来，放进鸿蒙工程的 third_party 目录。同时把 LICENSE 文件原样保留，这和开源合规有关，不能省。

这时候有一个关键操作：修改 Dart 侧的导入路径。原来代码里写的是 import 'package:pubspec_yaml/pubspec_yaml.dart';，本地化之后得把路径映射改到本地源码目录。这一步在 Dart 侧可以通过 pubspec_overrides.yaml 里的 dependency_overrides 指到本地路径来完成，不用逐个改 import，省了很多事。

依赖本地化最大的好处是构建机不再需要访问外网 Dart 包仓库。鸿蒙工程的环境通常很受限，外网访问可能被策略卡住，你总不能在每次构建时赌网络通畅。

4.2 桥接层实现：Dart 侧注册解析处理器

在 Dart 侧，我用 Flutter 标准的 MethodChannel 来处理来自 ArkTS 的请求。核心逻辑非常简单：监听一个固定的通道名，收到原始 YAML 字符串后调用 pubspec_yaml 的解析接口，把结果转成 JSON Map 返回。

dart复制import 'package:flutter/services.dart';
import 'package:pubspec_yaml/pubspec_yaml.dart';

class PubspecBridge {
  static const _channel = MethodChannel('pubspec_metadata_bridge');

  static Future<void> init() async {
    _channel.setMethodCallHandler((call) async {
      if (call.method == 'parse') {
        final rawYaml = call.arguments as String;
        final pubspec = Pubspec.parse(rawYaml);
        return _toJson(pubspec);
      }
      if (call.method == 'validate') {
        final rawYaml = call.arguments as String;
        try {
          Pubspec.parse(rawYaml);
          return {'valid': true};
        } catch (e) {
          return {'valid': false, 'error': e.toString()};
        }
      }
      throw MissingPluginException('Unsupported method: ${call.method}');
    });
  }

  static Map<String, dynamic> _toJson(Pubspec p) {
    return {
      'name': p.name,
      'version': p.version?.toString(),
      'environment': {
        'sdk': p.environment?.sdkConstraint?.toString(),
      },
      'dependencies': _dependencyMap(p.dependencies),
      'devDependencies': _dependencyMap(p.devDependencies),
      // flutter 段的 assets、fonts 等按需补充
    };
  }

  static Map<String, dynamic> _dependencyMap(DependencyContainer? container) {
    final result = <String, dynamic>{};
    container?.forEach((name, dep) {
      result[name] = {
        'type': dep.type.toString(),
        'description': dep.description?.toString(),
        // 不同类型依赖的描述结构不同，这里只做最小字段
      };
    });
    return result;
  }
}

ArkTS 侧的调用代码我就给个示意结构，因为不同版本的鸿蒙 Flutter SDK 对通道 API 的封装有差异，具体名称以你手头 SDK 文档为准：

typescript复制// ArkTS 侧：通过鸿蒙 Flutter 容器的通道发起调用
interface PubspecModel {
  name: string;
  version: string;
  environment: { sdk: string };
  dependencies: Record<string, DependencyModel>;
}

interface DependencyModel {
  type: string;
  description: string;
}
// channel.invokeMethod('parse', { yaml: rawYaml }) 
// 返回后按 PubspecModel 结构强转

这里要特别提醒：桥接协议一旦确定，ArkTS 侧的 interface 字段就不许随便改。加字段是兼容的，改字段名或者改类型会让旧版 Flutter 模块和鸿蒙壳之间出现静默失败。我习惯在协议里加 version 字段，每次解析返回数据都带上协议版本号，方便后续升级排查。

4.3 Dart 模型到 ArkTS 接口的类型映射

桥接层最费心思的不是传输，而是类型映射。Dart 和 ArkTS 的类型系统差异很大，我列了一张对照表：

最需要注意的是可选字段。pubspec.yaml 的很多字段不是必填的，比如 homepage、documentation、description，Dart 侧就是 nullable。桥接层一定要显式把 null 序列化出去，ArkTS 侧才能做空值判断。不要偷懒用默认值替代，否则你分不清“没写”和“写了空值”的区别，审计场景下这个区别很重要。

4.4 编译期和运行期我实际遇到的四个报错

第一个坑是版本约束导致的“另类空安全”。pubspec_yaml 较新的版本要求 Dart 3 才支持，但当时鸿蒙 Flutter 引擎内部锁的 Dart 版本还是 2.x，一编译就报语法错。解决办法是把 pubspec_yaml 降级到一个兼容 Dart 2.19 的旧版本，yaml 包版本也跟着锁。这里再次验证了“锁版本”的重要性。

第二个坑是通道传输大小。某次全量解析一个 assets 特别多的工程，assets 列表有几万字符，通过 MethodChannel 一次性传输直接超限，ArkTS 侧收到的是截断后的数据。解决方式是把 assets、fonts 这类大列表拆分拉取：先传核心字段，再按需拉取详细列表。如果你要治理的是大型工程，务必提前考虑这个限制。

第三个坑是 UTF-8 BOM。有几次 ArkTS 侧读出来的 YAML 文本开头多了一个不可见字符 \uFEFF，Pubspec.parse 直接炸。处理方式很简单，解析前先判断字符串开头是不是 \uFEFF，是就去掉。这不是 pubspec_yaml 的问题，但适配层的健壮性就需要处理这种外围脏数据。

第四个坑是 YAML 锚点和合并键。有的团队会在 pubspec.yaml 里用 <<: *defaults 这种 YAML 合并键来去重，yaml 包解析回来之后 anchor 默认不会自动展开，导致某些字段缺失。如果在治理结果里发现依赖数量比预期少，优先怀疑是不是合并键没有展开。

5. YAML 治理实战：适配完成之后，把它插进鸿蒙 CI 流水线

5.1 配置元数据资产的“治理”到底在治理什么

适配完成后，pubspec_yaml 桥接层相当于给我们提供了一个完整的 pubspec.yaml 对象模型，这时候才谈得上“治理”二字。我理解的 YAML 治理，主要是四件事。

第一是校验，确保提交上来的 pubspec.yaml 结构合法、字段类型正确、必填字段完整。第二是规范化，统一版本号的写法、统一依赖顺序、统一 YAML 缩进。第三是审计，追踪依赖变化、检查许可证、记录版本变更轨迹。第四是生成，基于模板生成新的 pubspec.yaml，避免手写导致格式漂移。

在鸿蒙工程里，我把这些治理动作做成了一个独立的检查步骤，排在 ArkTS 构建之前。只要 pubspec.yaml 校验不通过，整个构建直接红掉，不给“先构建完再说”的机会。这个门槛看起来严格，实际上是救命的：把错误挡在编译前，比让构建产物带病发布要划算得多。

5.2 一个可以直接用的配置治理脚本骨架

下面这个脚本是一个治理骨架，我在项目里就是拿它改的。它的功能包括：去掉 BOM、校验必填字段、校验版本号语义、检查 dependencies 是否被 dependency_overrides 静默覆盖。

python复制#!/usr/bin/env python3
import json
import re
import sys
from pathlib import Path

import yaml

MANDATORY_FIELDS = ("name", "version")
FORBIDDEN_OVERLAY = {"dependency_overrides"}

SEMVER_RE = re.compile(
    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
    r"(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)"
    r"(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
    r"(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
)


def load_pubspec(path: Path) -> dict:
    raw = path.read_text(encoding="utf-8")
    if raw.startswith("\ufeff"):
        raw = raw.lstrip("\ufeff")
    return yaml.safe_load(raw)


def validate(path: Path) -> int:
    pubspec = load_pubspec(path)
    errors = []

    for field in MANDATORY_FIELDS:
        if field not in pubspec:
            errors.append(f"缺少必填字段: {field}")

    version = pubspec.get("version")
    if version and not SEMVER_RE.match(str(version)):
        errors.append(f"版本号不符合语义化规范: {version}")

    for overlay in FORBIDDEN_OVERLAY:
        if overlay in pubspec:
            errors.append(f"检测到未允许的覆盖段: {overlay}")

    if errors:
        for err in errors:
            print(f"[ERROR] {path}: {err}", file=sys.stderr)
        return 1
    print(f"[OK] {path}: 元数据校验通过")
    return 0


if __name__ == "__main__":
    target = Path(sys.argv[1])
    sys.exit(validate(target))

这个脚本没有管依赖之间的版本冲突，因为那部分我需要借助 pubspec_yaml 返回的结构化数据来做。CI 里的完整流程是：先用 PyYAML 做快速骨架校验，再用桥接层返回的 JSON 做深度依赖分析，两步都过了才放行。

5.3 上线过程中踩过的三个 YAML 坑

第一个坑就是前面提到的锚点和合并键。YAML 的 <<: *defaults 在 PyYAML 里默认会被展开，但 Dart 的 yaml 包不会，两边解析结果不一致。治理脚本里我用的是 PyYAML 做快速校验，桥接层用的是 pubspec_yaml，两边数出来的依赖数量偶尔对不上。后来统一口径：以 pubspec_yaml 的解析结果为准，PyYAML 只负责看文件整体格式和编码问题。

第二个坑是注释丢失。pubspec_yaml 序列化出来的是重新格式化的 YAML，注释全部丢弃。如果治理流程里有“把修改后的 pubspec.yaml 写回仓库”这一步，一定要意识到写回的文件是没有注释的。很多工程会在 pubspec.yaml 里写变更说明、遗留问题，这些注释对审计很有价值。所以我的建议是：治理结果只做展示和校验，绝不要拿序列化结果直接覆盖原始文件。写回操作一律由脚手架生成新文件，原始文件留档。

第三个坑是换行符。很多文件从 Windows 机器提交上来，行尾是 CRLF，在 Linux 构建机上 diff 会显示整片文件都变了。这个不解决，代码评审的人会疯掉。治理脚本里统一在读取后按 LF 处理，或者写回时用 git config core.autocrlf 规范整个仓库。细节问题，但实际踩到才知道疼。

6. 验证压测与后续维护的一揽子建议

6.1 正确性验证：用全字段样例文件来回读

适配做完，最重要的事情是验证。我造了一个全字段的 pubspec.yaml 样例，把 name、version、environment、dependencies（hosted/git/path/sdk 四种都覆盖）、dev_dependencies、flutter 段的 assets、fonts、plugins 全部填上，然后跑一遍“解析→序列化→再解析”的回读测试。

重点验证几个地方：

这类验证最好固化成自动化测试，塞进 CI。我建议你保留一份“全字段样例 + 期待 JSON”作为基准数据，每次升级 pubspec_yaml 版本后跑一次，能很直观地看出上游行为有没有变化。

6.2 性能与内存表现

性能方面，桥接层的主要开销在通道传输和 JSON 解析，pubspec_yaml 本身的解析耗时反而不是瓶颈。实测一个 dependencies 数量在一百个上下的中型工程，Dart 侧解析耗时基本在几十毫秒量级，序列化成 JSON 也差不多。ArkTS 侧拿到 JSON 再做类型转换，毫秒级完成，整体体感是无感的。

真正要关注的是超大 assets 列表的传输耗时和内存峰值。如果你把整个 Flutter 资源清单一次性打过去，内存占用会瞬间飙升。我的经验是核心字段一次传，assets 按回调分页拉取，既能控制峰值内存，又能避免通道超限。

6.3 后续维护注意事项

pubspec_yaml 是活跃维护的库，上游会修 bug、加字段，这本身是好事，但你要把它当成“需要定期同步的依赖”来看待。

我的建议是：锁一个大版本，比如固定 2.x 系列，每个月抽时间看一次上游 CHANGELOG。如果新版本有影响模型结构的改动，先在测试分支跑一遍回读测试，确认不破坏 ArkTS 侧接口再合并。不要随手升到最新号，因为你上游一个字段改名，可能就要连带改桥接层、ArkTS 接口、治理脚本三方代码。

另外，ArkTS 侧的 PubspecModel 接口要多留余地。加字段用可选类型，不要轻易删字段，也不要改字段名。存量环境里可能有旧的 Flutter 模块还在跑，协议僵化一点、冗余一点，换来的是不炸线。

如果你也是因为鸿蒙侧要统一读 pubspec.yaml 才搜到这篇文章，我最后提醒一句：适配本身不难，难的是把“配置元数据”当成一个正经的资产来维护。桥接层做好、验证用例备齐、版本锁定策略落地，后面你每一个依赖审计、版本对齐、合规巡检的需求，都能在同一个模型上平趟过去。千万别图省事走回正则解析的老路，那是把债越欠越多。