---
url: /zh/build/pipeline-visualization.md
---
## 概述

基于 **Pipeline as Code** 的理念，流水线配置文件需要手动编写。当配置内容较为复杂，尤其是使用 [include](./grammar.md#include) 引入模板时，开发者常常会面临以下疑问：语法是否正确？最终的流水线内容是否符合预期？流水线是否会按预期触发？

本文将以代码 Push 事件为例，从 **编写** -> **预览** -> **Flow** -> **事件追踪** 四个步骤，帮助您实现流水线配置的"所见即所得"，确保流水线的高效管理和可靠运行。

## 编写

开始编写前，建议先配置代码编辑器的 [语法检查和自动补全](./configuration.md#语法检查和自动补全) 功能，帮助快速发现语法错误并提供代码片段建议。

### 配置示例

以下是一个引用流水线模板文件的示例：

```yaml title="template.yml"
main:
  push:
    - stages:
        - name: pipeline 1 stage 1
          script: echo "pipeline 1 stage 1"
        - name: pipeline 1 stage 2
          script: echo "pipeline 1 stage 2"
```

```yaml title=".cnb.yml"
include:
  # 此处引用当前仓库当前分支的文件，也可以引用其他仓库的文件
  - template.yml
main:
  push:
    - stages:
        - name: pipeline 2 stage 1
          script: echo "pipeline 2 stage 1"
        - name: pipeline 2 stage 2
          script: echo "pipeline 2 stage 2"
```

### 使用建议

* 使用 `include` 复用流水线模板，减少重复配置，提高维护效率
* 支持引用其他仓库模板文件的网页地址
* 详细的 `include` 语法请参考 [include 配置](./grammar.md#include)

## 预览

编写完成后，将配置文件提交并推送到远端仓库，然后在仓库首页查看 `.cnb.yml` 文件并切换到 `预览` 选项卡。

### 预览效果

此时，您可以看到 `template.yml` 的内容已成功合并到 `.cnb.yml` 中：

![preview](/images/build/pipeline-visualization/preview.zh.png)

### 功能特性

* **配置验证**：确认最终配置是否符合预期
* **合并展示**：展示 `include` 引入模板与主配置的合并结果
* **问题排查**：避免模板引用错误或配置冲突导致运行失败
* **语法检查**：自动检测语法错误，运行前发现问题

## Flow

在 `.cnb.yml` 文件页面点击 `Flow` 选项卡，直观查看当前分支下 `push` 事件触发的流水线配置。

### 可视化视图

![flow](/images/build/pipeline-visualization/flow.zh.png)

### 视图说明

Flow 视图以流程图形式展示流水线结构，包括：

* **分支标识**：显示触发流水线的目标分支
* **触发事件**：显示当前查看的事件类型（如 `push`）
* **流水线分组**：事件下每条线代表一条独立的流水线
* **阶段展示**：流水线内的各个阶段按执行顺序排列

### 功能价值

* **可视化展示**：直观展示流水线结构和执行顺序
* **触发验证**：验证流水线是否按预期触发
* **配置检查**：排查配置问题，如遗漏步骤
* **依赖关系**：清晰展示任务间的并行或串行关系

## 事件追踪

在 Git 事件触发后，通过 `云原生构建列表` > `历史事件` 查看流水线触发情况。

### 事件列表

![history-events](/images/build/pipeline-visualization/history-events-entry.zh.png)

列表中展示本次触发的两个 CI 事件：`push` 和 `commit.add`。

**CI 事件信息说明**：

* **事件类型**：显示 `push`、`commit.add`、`pull_request` 等 CI 事件类型
* **触发状态**：已触发的事件显示为可点击状态
* **未触发说明**：未触发的事件不可点击，鼠标悬停可查看原因

### push 事件

点击 `push` 事件可跳转至构建详情页，查看流水线执行状态和日志。

![event-detail-push](/images/build/pipeline-visualization/event-detail-push.zh.png)

**详情页功能**：

* **状态展示**：提供流水线的实时执行状态，包括成功、失败或进行中
* **日志查看**：查看详细的日志信息，帮助定位问题或验证执行结果
* **步骤追踪**：查看每个阶段的执行情况和耗时
* **环境信息**：显示构建环境、镜像、资源使用等信息
* **重试功能**：支持全量或选择性重新执行流水线、任务

### commit.add 事件

未触发的事件不可点击，鼠标悬停可查看未触发原因。

![event-detail-commit-add](/images/build/pipeline-visualization/event-detail-commit-add.zh.png)

**未触发原因**：

* 分支下无 `.cnb.yml`，或 `.cnb.yml` 语法错误
* 事件触发的条件未满足，如事件不匹配

## 最佳实践

为了确保流水线的高效管理，建议遵循以下最佳实践：

### 1. 模块化配置

将通用的流水线步骤抽象为模板，通过 `include` 复用，减少重复配置，提高可维护性。

### 2. 定期检查

修改配置后使用预览和 Flow 验证正确性：

* **预览**：确认 `include` 合并结果
* **Flow**：验证流水线结构和任务流程

### 3. 事件监控

通过事件追踪功能实时监控流水线触发和执行：

* 查看 `历史事件` 确认触发情况
* 鼠标悬停未触发事件查看原因
* 通过构建详情页跟踪执行进度

### 4. 日志分析

构建失败时根据日志分析原因：

* 查看失败阶段的详细日志
* 检查环境变量、依赖和脚本执行
* 根据错误信息调整配置并重新提交

### 5. 增量验证

复杂配置变更采用增量验证：

* 在测试分支验证配置
* 使用预览和 Flow 确认效果
* 测试通过后再合并到主分支

## 注意事项

* **权限检查**：预览功能仅检查 `include` 文件的访问权限，不验证 `allow_*` 属性。事件触发后，系统会检查 `allow_*` 属性确认访问权限。
* **事件范围**：`历史事件` 仅展示 `push`、`tag_push`、`pull_request` 等代码相关仓库事件，不展示 `tag_deploy`、`web_deploy`、`API事件`、`定时任务` 等非代码相关事件。
* **重新构建**：重新构建触发的流水线不会展示在 `历史事件` 中。

***

通过以上步骤和最佳实践，您可以轻松实现流水线配置的编写、预览、流程查看和事件追踪，确保流水线按预期运行，提升开发效率和系统可靠性。

如需了解更多流水线配置的语法细节，请参考 [语法手册](./grammar.md) 和 [配置文件](./configuration.md)。