3. 模板引擎语法：Go模板基础、模板函数与管道、流程控制（if/with/range）、变量作用域与上下文

Helm 的核心价值在于通过 Go 模板引擎 将静态的 YAML 清单转化为动态、可配置的部署描述。本章深入剖析模板引擎的四大支柱：基础语法、函数与管道、流程控制以及变量作用域。掌握这些知识，是编写可维护、可复用的 Helm Chart 的必备技能。

3.1 Go 模板基础：数据注入与输出

Go 模板使用 {{ 和 }} 作为定界符（Delimiters），将模板指令与普通文本区分开。最基础的操作是将 values.yaml 中的值注入到模板中。

3.2 模板函数与管道：数据转换的艺术

Helm 内置了超过 60 个模板函数，并通过 管道（Pipeline） 机制串联，实现复杂的数据变换。管道符号 | 将前一个命令的输出作为后一个命令的输入。

3.2.1 常用内置函数

3.2.2 管道链实战

{{- /* 将 values.yaml 中的标签转换为大写，并用双引号包裹 */ -}}
labels:
  environment: {{ .Values.environment | upper | quote }}
  team: {{ .Values.team | default "platform" | quote }}

{{- /* 将复杂的资源配置安全地嵌入 Deployment */ -}}
resources:
{{- toYaml .Values.resources | nindent 10 }}

3.3 流程控制：if/with/range

流程控制让模板具备条件渲染和循环迭代的能力，是构建灵活 Chart 的核心。

3.3.1 条件判断：if/else

根据值的真假（布尔值、非空字符串、非零数字、非空列表/字典）决定是否渲染代码块。

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}-ingress
spec:
  rules:
    - host: {{ .Values.ingress.host }}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ .Release.Name }}-svc
                port:
                  number: {{ .Values.service.port }}
{{- else }}
# Ingress 未启用，跳过创建
{{- end }}

3.3.2 作用域切换：with

with 将当前上下文 . 临时切换到指定对象内部，简化深层嵌套属性的访问。如果指定对象为空或不存在，则跳过整个块。

{{- /* 传统写法：每次都要写 .Values.database */ -}}
host: {{ .Values.database.host }}
port: {{ .Values.database.port }}

{{- /* 使用 with 简化 */ -}}
{{- with .Values.database }}
host: {{ .host }}
port: {{ .port }}
{{- end }}

3.3.3 循环迭代：range

range 用于遍历数组或字典，每次迭代都会改变当前上下文 .。

{{- /* 遍历 values.yaml 中的 sidecarContainers 列表 */ -}}
{{- range .Values.sidecarContainers }}
- name: {{ .name }}
  image: {{ .image }}
  ports:
    - containerPort: {{ .port }}
{{- end }}

{{- /* 遍历字典，同时获取键和值 */ -}}
{{- range $key, $value := .Values.labels }}
  {{ $key }}: {{ $value }}
{{- end }}

3.4 变量作用域与上下文

理解 . 的变化是避免模板错误的关键。Helm 模板的作用域遵循以下规则：

• 根上下文： 模板最外层 . 指向 Values、Release、Chart、Files 等顶级对象的集合。
• 作用域切换： with 和 range 会改变 . 的指向。在块内部，. 代表当前迭代的元素或指定的对象。
• 全局访问： 使用 $ 前缀可以始终引用根上下文，无论当前处于多少层嵌套。
• 变量赋值： 使用 $var := value 可以在当前作用域创建局部变量，避免重复计算或保存上下文。

{{- /* 在 range 内部同时使用局部变量和全局上下文 */ -}}
{{- $root := . }}  {{- /* 保存根上下文到变量 */ -}}
{{- range .Values.containers }}
- name: {{ .name }}
  image: {{ .image }}
  env:
    - name: RELEASE_NAME
      value: {{ $root.Release.Name }}  {{- /* 使用变量访问全局 */ -}}
    - name: POD_NAME
      value: {{ $.Release.Name }}      {{- /* 使用 $ 直接访问根上下文 */ -}}
{{- end }}

3.5 模板引擎核心流程 SVG

下图展示了 Helm 模板引擎从数据源到最终 YAML 输出的完整处理流程，重点突出作用域切换与管道变换。

3.6 常见陷阱与避坑指南