html/template 渲染简历需四点避坑：1. 富文本字段用 template.HTML 类型；2. 模板路径用 embed.FS 或绝对路径；3. JSON 反序列化需导出字段+json tag；4. CSS/图标须内联或用本地服务预览。
用 html/template 渲染简历 HTML 时，结构怎么组织才不翻车
Go 的 html/template 默认会转义所有输出，这是好事，但也是新手写简历模板时最常懵圈的点：明明数据传进去了，页面上却显示一堆 <p> 而不是真实标签。关键不是“怎么渲染”，而是“哪些内容该信任、哪些必须显式声明可执行”。
简历里肯定有格式化段落、技能列表、项目描述带链接——这些都需要绕过自动转义，但又不能全关（否则 XSS 风险）。正确做法是用 template 函数或 template 动作配合 html 类型变量。
- 把富文本字段（如
Summary、Project.Description）定义为template.HTML类型，而非string - 在 struct 定义里明确标注：
type Resume struct { Name string Summary template.HTML // ← 不是 string Skills []string } - 渲染前用
template.HTMLEscapeString或直接拼接确保安全；别用strings.ReplaceAll手动塞 HTML 标签
ParseFiles 加载模板失败的典型原因和排查路径
常见错误信息是 template: "resume.html" is undefined 或 open templates/resume.html: no such file or directory，根本不是语法问题，而是 Go 的工作目录和 ParseFiles 路径解析逻辑不一致导致的。
- Go 程序默认以
os.Executable()所在目录为起点，不是go run所在目录 —— 所以硬写templates/resume.html很可能找不到 - 推荐用
filepath.Join(filepath.Dir(os.Args[0]), "templates", "resume.html")构造绝对路径 - 或者更稳妥：把模板嵌入二进制，用
embed.FS（Go 1.16+），避免部署时漏文件import _ "embed" //go:embed templates/*.html var templateFS embed.FS t := template.Must(template.New("").ParseFS(templateFS, "templates/*.html"))
简历数据从 JSON 文件读取时，json.Unmarshal 容易忽略的字段映射细节
很多人把 JSON 字段名起成 full_name、job_title，然后 struct 字段用 FullName、JobTitle，却不加 tag，结果反序列化后全是空值 —— Go 的 json 包默认只识别导出字段 + 小写首字母匹配或显式 tag。
立即学习“go语言免费学习笔记（深入）”；
- struct 字段必须首字母大写（导出），且需配
json:"full_name"tag 才能对应type Resume struct { Name string `json:"full_name"` Title string `json:"job_title"` Projects []Project `json:"projects"` } type Project struct { Name string `json:"name"` Description string `json:"description"` // ← 注意大小写和下划线 } - 如果 JSON 里有可选字段（比如
linkedin_url可能为空），字段类型建议用*string或sql.NullString，避免零值污染渲染 - 用
json.RawMessage延迟解析复杂嵌套字段（如自定义 HTML 片段），防止提前 panic
生成静态 HTML 文件后，CSS 和字体加载不生效的本地路径陷阱
本地打开生成的 resume.html，发现样式空白、图标不显示，十有八九是用了相对路径引用 style.css 或 fonts/，但浏览器用 file:// 协议加载时，部分 CSS @import / font-face 会被同源策略拦截（尤其 macOS Safari 和新版 Chrome）。
- 不要依赖
<link rel="stylesheet" href="css/style.css">这种相对路径 —— 生成时直接把 CSS 内容读入template.CSS类型字段，内联到<style>标签里 - 图标优先用 inline SVG 或 base64 编码的 data URL，避开外部字体文件请求
- 如果非要外链，生成后用
http.ServeFile启个临时服务预览：http.ListenAndServe(":8080", http.FileServer(http.Dir(".")))浏览器访问http://localhost:8080/resume.html
真正卡住人的从来不是语法，而是模板路径、JSON tag、HTML 类型转换、本地文件协议限制这四点交叉作用。每个环节单独看都很简单，串起来就容易漏掉一环 —— 比如改了 struct tag 却忘了更新 JSON 示例，或者内联了 CSS 却还在 HTML 里留着 href。多跑两遍 go build && ./resume，比查文档更快定位哪一层断了。
