因为需控制渲染逻辑、集成内部cms、统一元信息格式，现成工具插件机制反而更重；golang的html/template和文件遍历能力足以构建轻量静态生成器，核心是“轮子必须听你指挥”。
为什么不用 Hugo/Jekyll 而要自己写一个？
因为你要控制渲染逻辑、集成内部 CMS 数据源、或强制统一元信息格式——这时候现成工具的插件机制反而更重。golang 的 html/template 和文件遍历能力足够撑起一个轻量静态生成器，关键不是“造轮子”，而是“轮子必须听你指挥”。
常见错误现象：template.ParseFiles 报 no such file or Directory，其实是工作目录没切对；或者 Execute 后页面空白，大概率是模板里用了未导出字段（首字母小写）。
- 所有模板路径用绝对路径或基于
os.Getwd()拼接，别信相对路径 - 数据结构字段必须首字母大写，否则
html/template读不到 - 避免在模板里调用函数做 I/O 或复杂计算，提前在 Go 层准备好数据
如何组织内容文件与模板的映射关系？
静态站点本质是「内容 → 模板 → HTML」的单向流水线。Golang 不自带约定式路由，得自己定义规则：比如把 content/posts/hello.md 渲染进 layouts/post.html，再输出到 public/posts/hello/index.html。
使用场景：多栏目（posts / docs / projects）需要不同模板，但共用 header/footer；或同一份 Markdown 要生成两个版本（带 toc / 不带 toc）。
立即学习“go语言免费学习笔记（深入）”；
- 用
filepath.Walk扫描content/目录，按子目录名决定用哪个layout - 模板中通过
.Layout字段或文件路径前缀判断，而不是硬编码 if-else - Markdown 解析推荐
goldmark（比blackfriday更活跃），它返回ast.Node，可安全注入自定义渲染器
怎么处理 CSS/js 等静态资源的路径与哈希？
直接拷贝会丢更新感知，不加哈希又没法长期缓存。Golang 没有 webpack，但可以用 crypto/sha256 + io.copy 在构建时算哈希，再重命名文件并更新 HTML 中的引用。
性能影响：每次构建都重新哈希所有静态文件，100+ 文件时会明显拖慢；兼容性上注意 windows 路径分隔符（filepath.Join 自动处理）。
- 只对
assets/下的.css、.js、.png等扩展名做哈希，忽略.map或.lock - HTML 中引用写成
<link rel="stylesheet" href="/css/main.<%=%20.CSSHash%20%>.css">，模板里传入CSSHash字段 - 用
os.Symlink替代复制可加速开发期构建（但部署时仍需真实文件）
生成过程出错时如何快速定位？
最常卡在模板执行失败（语法错、字段空指针）、Markdown 解析 panic、或并发写文件冲突。Golang 默认 panic 会中断整个生成流程，不利于排查。
容易踩的坑：template.Execute 返回 Error 但被忽略；os.WriteFile 写入 public/ 前没确保父目录存在；并发调用 os.MkdirAll 可能报 file exists 但不是真错误。
- 每个
template.Execute后立刻检查 error，打印出触发的文件路径和行号 - 用
os.MkdirAll(path.Dir(dest), 0755)确保输出目录存在，别依赖上一步 - 生成任务用
sync.WaitGroup控制并发，但别超过 CPU 核心数，IO 密集型任务 4–8 协程足够
真正麻烦的是模板继承链里某一层漏了 {{define}} 或嵌套错位，这种错误不会报 panic，只会静默丢内容——建议在开发期加个校验步骤：解析所有模板，确认每个 {{template}} 引用的块都已定义。