📚 课程目录第3章 GitLab依赖管理机制

3. GitLab依赖管理机制

GitLab 的依赖管理并不是一个独立开关，而是一条从“仓库里有什么依赖声明文件”到“这些依赖之间是什么关系”再到“最终形成可审计清单”的处理链。理解这条链，才能解释为什么同一个项目在流水线里有时能报出依赖，有时却只显示“未检测到依赖”，也才能判断安全扫描结果是否可信。

GitLab 依赖管理的核心由三部分组成：依赖文件识别、依赖图谱构建和依赖清单生成。识别决定“从哪里读”，图谱决定“读出来之后如何连接”，清单决定“最终以什么形式呈现给用户和下游系统”。三者缺一不可，且顺序不能颠倒。

依赖文件识别：先确定扫描入口

GitLab 不会盲目扫描仓库中的所有文件，而是依据文件类型和路径模式来识别依赖声明文件。常见的识别对象包括：

包管理器清单文件：如 package.json、requirements.txt、Pipfile、pom.xml、build.gradle、go.mod、Cargo.toml、composer.json 等。
锁文件：如 package-lock.json、yarn.lock、Pipfile.lock、poetry.lock、go.sum、Cargo.lock 等。锁文件通常比清单文件更精确，因为它记录了实际解析到的版本和传递依赖。
多模块或子目录中的声明文件：例如 monorepo 中 packages/a/package.json 与 services/b/pom.xml 需要分别识别。

识别阶段的关键判断依据是文件类型 + 路径 + 项目配置。GitLab 会结合项目语言、CI 配置以及依赖扫描组件（如 Gemnasium、Dependency Scanning）的默认规则来决定是否纳入。如果文件不在默认识别范围内，或者路径被 .gitlab-ci.yml 中的规则排除，就不会进入后续图谱构建。

实际排查时，如果流水线显示“未检测到依赖”，第一步不是怀疑扫描器坏了，而是确认依赖文件是否被识别：文件是否在仓库根目录或已配置的子路径下，文件名是否与扫描器支持的类型一致，以及 CI 规则是否把该路径排除。

依赖图谱构建：从平面列表到有向关系

识别到文件后，GitLab 会解析其中的依赖声明，并构建依赖图谱。图谱的本质是一个有向图：节点是依赖包（含名称和版本），边表示“谁依赖谁”。直接写在清单文件中的是直接依赖，由直接依赖继续引入的是传递依赖。

以 package.json 为例，假设项目声明了：

{
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "4.17.21"
  }
}

解析后，express 和 lodash 是直接依赖。但 express 自身又依赖 body-parser、cookie、debug 等，这些就是传递依赖。图谱构建时，GitLab 会尽量展开这些层级，形成“项目 → 直接依赖 → 传递依赖”的树状或图状结构。

图谱构建的准确性高度依赖锁文件。如果只有 package.json 而没有 package-lock.json，版本范围（如 ^4.18.2）无法唯一确定，图谱可能只能给出候选版本或无法完整展开传递依赖。因此，锁文件是依赖图谱稳定性的关键输入。

依赖清单生成：从图谱到可读结果

图谱构建完成后，GitLab 会将其转换为依赖清单。清单通常包含以下字段：依赖名称、版本、依赖类型（直接/传递）、所属包管理器、许可证信息，以及与已知漏洞的关联标识。清单的用途主要有三个：在合并请求中展示依赖变化、在安全面板中关联漏洞、以及作为下游合规审计的输入。

清单生成时有一个容易被忽略的细节：同一依赖可能以不同版本出现在不同路径下。例如 lodash 在项目根目录是 4.17.21，但某个传递依赖内部又引入了 4.17.20。图谱中会保留两个节点，清单中也会分别列出。安全扫描会分别检查这两个版本，而不是只检查其中一个。

实际排查：依赖识别失败的常见原因

当依赖清单为空或明显不完整时，可以按以下顺序排查：

确认文件是否被识别：检查依赖文件是否在仓库根目录或已配置的扫描路径下，文件名是否与扫描器支持的类型一致。
确认锁文件是否存在：只有清单文件而没有锁文件时，传递依赖可能无法展开，清单会明显偏少。
确认 CI 规则是否排除：检查 .gitlab-ci.yml 中是否对依赖扫描任务设置了 rules 或 only/except，导致该任务未执行。
确认扫描器版本与语言支持：不同版本的 Dependency Scanning 组件支持的语言和文件类型不同，需确认当前版本是否覆盖项目所用包管理器。

依赖清单的完整性直接决定后续漏洞扫描的覆盖面。如果清单中缺少传递依赖，安全面板就不会显示这些依赖引入的漏洞，容易造成“看起来没问题”的假象。因此，锁文件应纳入版本控制，且不应被 .gitignore 排除。

小结

GitLab 依赖管理机制可以概括为一条清晰的链路：识别依赖文件 → 构建依赖图谱 → 生成依赖清单。识别阶段决定扫描入口，图谱阶段决定依赖之间的连接关系，清单阶段决定最终呈现和下游消费。锁文件是贯穿三个阶段的稳定输入，CI 规则和扫描器版本则决定这条链路是否真正执行。理解这条链路，才能在依赖扫描结果异常时快速定位问题环节，而不是停留在“重新跑一次流水线”的层面。