基于Golang的简易维基(Wiki)服务_支持HTML模板渲染

html/template 更适合 wiki 渲染，因其支持上下文感知转义，在防范 xss 的同时允许通过 template.html 显式注入安全 html；而 text/template 会过度转义导致页面显示为纯文本。

为什么 html/template 比 text/template 更适合 Wiki 页面渲染

Wiki 页面天然包含用户提交或编辑的 HTML 片段（比如 `

`、``、代码块），直接用 text/template 渲染会导致转义过度——所有尖括号都被变成 ，页面一片纯文本；而 <code>html/template 在识别上下文（如标签内、属性值、JS 字符串）后做**有上下文的转义**，既防 XSS，又允许安全的 HTML 输出。

关键点：必须用 template.HTML 显式标记可信 HTML，否则仍会被转义：

func renderPage(w http.ResponseWriter, title string, content string) {
    // content 是从 Markdown 转换来的 HTML 字符串，已过滤过 script 标签
    data := struct {
        Title   string
        Content template.HTML // ← 必须这样声明，不能是 string
    }{title, template.HTML(content)}
    t.Execute(w, data)
}

常见错误现象：Content 声明为 string，但传入 template.HTML(...) → 编译不报错，运行时仍被转义；或者漏掉类型断言/转换，导致空内容。

如何安全地把 Markdown 转成 HTML 并注入模板

别自己手写正则解析 Markdown。Go 生态里最轻量且可控的是 blackfriday/v2（已归档但稳定）或更现代的 goldmark。前者 API 简单，后者扩展性好、默认禁用危险 HTML（如 <script></script>）。

立即学习“go语言免费学习笔记（深入）”；

实操建议：

• 用 goldmark.WithExtensions(goldmark.WithoutExtensions()) 关闭所有扩展，只留基础语法，避免意外解析出危险结构
• 务必启用 goldmark.WithRendererOptions(html.WithUnsafe()) —— 否则连 <img alt="基于Golang的简易维基(Wiki)服务_支持HTML模板渲染" > 都被过滤，Wiki 失去实用性
• 转换后得到的 HTML 字符串，需经一次白名单清洗（例如用 bluemonday 库），再转成 template.HTML

示例片段：

md := goldmark.New(
    goldmark.WithExtensions(goldmark.WithoutExtensions()),
    goldmark.WithRendererOptions(html.WithUnsafe()),
)
var buf bytes.Buffer
if err := md.Convert([]byte(src), &buf); err != nil {
    http.Error(w, "parse error", http.StatusInternalServerError)
    return
}
cleaned := bluemonday.UGCPolicy().Sanitize(buf.String())
t.Execute(w, map[string]interface{}{
    "Content": template.HTML(cleaned),
})

静态资源路径怎么配才不会 404（特别是 CSS 和图标）

Wiki 页面里引用 /static/style.css，但 Go 的 http.FileServer 默认不处理带前缀的路径映射，容易出现「CSS 加载了，但字体图标 404」这类问题。

Knowt

Knowt是一款AI驱动的在线学习工具

下载

根本原因：文件服务器不知道 /static/ 对应磁盘上哪个目录，而且没设置 MIME 类型或缓存头。

正确做法：

• 用 http.StripPrefix("/static/", http.FileServer(http.Dir("./static")))，而不是直接 http.FileServer(http.Dir("./static"))
• 确保 ./static 目录存在，且包含 style.css、favicon.ico 等，路径大小写敏感（Linux 下 Favicon.ico ≠ favicon.ico）
• 如果用了自定义模板里的 <link rel="icon">，注意浏览器会自动请求 /favicon.ico，得单独路由处理或放对位置

一个易忽略点：开发时用 go run，工作目录是项目根；但部署成二进制后，./static 是相对于执行路径的，不是二进制所在目录 —— 所以最好用 os.Executable() 定位。

为什么页面编辑保存后刷新还是旧内容

不是模板没重载，是 Markdown 源文件读取后被缓存了，或者 HTML 渲染结果被意外复用。

典型场景：

• 把 template.ParseFiles() 放在 init() 或服务启动时 —— 模板本身不会热更新，但这是正常行为；真正的问题常出在「内容缓存」
• 用 ioutil.ReadFile（或 os.ReadFile）读取 .md 文件后，没检查返回错误，文件不存在时静默返回空字符串，页面就显示空白
• HTTP 响应头没设 Cache-Control: no-cache，浏览器缓存了上一次渲染结果，看起来像“没更新”

调试建议：在 handler 开头加一行日志，打印实际读到的文件长度和前 50 字符，确认是否真读到了新内容。模板渲染本身无状态，问题几乎总在数据源或传输链路上。

复杂点在于：Wiki 的“实时性”其实是假象，它依赖文件系统 I/O 和 HTTP 缓存控制的配合，任何一环松动，用户就会觉得“改了没用”。