embed.fs 是唯一靠谱的方案：用 //go:embed 加载模板避免路径问题；yaml 渲染需精确控制空白（{{-}}）；环境变量应在 go 层预处理结构体；模板传入前须规整 nil 字段。
模板路径加载失败：embed.FS 是唯一靠谱的方案
运行时找不到 templates/*.tmpl 不是权限或拼写问题，而是工作目录不可控——CI 构建、Docker 容器、IDE 启动都会让 os.Getwd() 指向意外位置。硬编码相对路径（如 "./templates/config.tmpl"）在任意环境都可能 panic。
用 embed.FS 编译进二进制，彻底规避路径问题：
import _ "embed"
<p>//go:embed templates/*.tmpl
var tmplFS embed.FS</p><p>t := template.Must(template.New("").ParseFS(tmplFS, "templates/*.tmpl"))</p>
- 必须加
//go:embed注释，且路径是相对于该 Go 文件所在目录 -
ParseFS自动注册所有匹配文件为命名模板，后续可用t.Lookup("config.tmpl") - 别用
template.ParseFiles或ParseGlob—— 它们依赖运行时路径，不是构建时路径
YAML 渲染缩进错乱：空白控制必须精确到每个 {{-}}
YAML 对空格极其敏感，text/template 默认保留所有换行和前导空格，导致 data: 下的键缩进错位、解析失败。这不是语法写错，而是空白没裁剪干净。
关键规则只有两条：
- 每行模板指令左侧的空白（包括换行符）用
{{- }}去掉；右侧空白（含换行）用{{-}}去掉 - 多行结构（如 map 或 list）必须整个块写在单个
{{range}}内，不能把{{end}}单独换行
错误写法（缩进崩坏）：
data:
{{range $k, $v := .Data}}
{{$k}}: {{$v}}
{{end}}
正确写法（严格控制空白）：
data:{{- range $k, $v := .Data }}
{{$k}}: {{$v}}{{- end}}
环境变量注入不安全：预处理结构体，禁止在模板里调 .Env.FOO
模板里写 {{.Env.DB_HOST}} 看似方便，但会导致三类问题：缺失环境变量时不报错（渲染出空字符串）、类型无法校验（REPLICAS 是字符串还是 int？）、单元测试无法 mock。
正确做法是在 Go 层完成数据组装：
- 定义明确结构体，例如
type Config struct { Name string; Replicas int; Region string } - 用
os.Getenv+strconv.Atoi等预处理，失败直接log.Fatal，不留给模板兜底 - 传入模板的数据必须是完整、非 nil、类型确定的值，模板只负责格式化，不负责逻辑判断
禁止以下行为：
-
{{index .Env "DB_HOST"}}—— map 查找无类型、无默认值 -
{{if .Env.DEBUG}}--debug{{end}}—— 模板承担配置合法性检查职责
生成 Go 代码时 panic：nil 字段访问必须提前防御
模板里写 {{.Spec.Description.Text}} 很常见，但如果 Description 是 *Description 且为 nil，就会触发 template: nil pointer evaluating interface {}.Text。
最稳妥的防御方式不是靠 {{with}}，而是在传入前做字段规整：
- 指针字段转为值类型：
Desc: if spec.Description != nil { spec.Description.Text } else { "" } - 切片字段统一初始化：
Endpoints: spec.Endpoints→ 若spec.Endpoints == nil，先赋值为[]string{} - 对必须保留 nil 语义的字段（如“跳过生成某段代码”），提供显式方法：
func (s *Spec) HasValidator() bool { return s.Validator != nil }，模板里调{{if .HasValidator}}
永远不要假设模板能优雅处理 nil —— 它不会，只会 panic。
复杂点在于 YAML 缩进和 Go 代码生成对空白的容忍度完全不同，前者要求严格裁剪，后者需要保留特定换行；同一套模板逻辑很难兼顾二者，建议按目标格式拆分成独立模板实例。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
