解决 Goldmark HardWraps 编译报错及单例初始化指南

这个错误是因为 goldmark 官方库及扩展包中并没有 extension.WithHardLineBreak 或 extension.NewRenderer 这个 API。这是一个常见的拼写或记忆混淆错误。

在 goldmark 中，将普通换行（Soft Line Break）直接渲染为 <br>（即硬换行 Hard Line Break）的正确配置项是 html.WithHardWraps()，它属于 github.com/yuin/goldmark/renderer/html 包。

同时，你的直觉非常准确。goldmark.New() 内部包含大量的反射、对象创建和配置解析工作，每次渲染都重新 New 会造成极大的性能浪费和 GC 压力。由于 goldmark.Markdown 实例是并发安全的（Goroutine-safe），我们必须将其作为全局单例，在应用启动（例如 init 函数）时初始化一次。

下面是完整的解决方案和最佳实践代码：

1. 导入正确的库

首先需要使用 go get 引入标准的 goldmark 库：

go get github.com/yuin/goldmark

2. 正确的初始化代码（使用 init 单例）

请创建或修改你的 markdown 转换工具包：

package mymarkdown

import (
	"bytes"
	"sync"

	"github.com/yuin/goldmark"
	"github.com/yuin/goldmark/renderer/html"
)

// 定义全局单例实例
var md goldmark.Markdown

func init() {
	// 在 init 函数中一次性完成初始化，避免每次调用时重复创建
	md = goldmark.New(
		goldmark.WithRendererOptions(
			// html.WithHardWraps() 对应渲染器中的硬换行配置（将 
 渲染为 <br />）
			html.WithHardWraps(),
			// 如果需要支持 HTML 标签（默认是转义的），可以加上这一行：
			// html.WithUnsafe(), 
		),
	)
}

// ConvertToHTML 将 Markdown 文本安全高效地转换为 HTML 字节流
func ConvertToHTML(src []byte) ([]byte, error) {
	var buf bytes.Buffer
	// md 实例是并发安全的，可以多协程同时调用 Convert
	if err := md.Convert(src, &buf); err != nil {
		return nil, err
	}
	return buf.Bytes(), nil
}

3. 为什么必须在 init 中初始化？

1. 避免性能瓶颈：goldmark.New() 会在底层初始化各种 AST（抽象语法树）解析器和渲染器，频繁创建会导致 CPU 占用飙升和内存频繁申请/释放。
2. 并发安全：goldmark.Markdown 接口的底层实现保证了在初始化完成后，其 Convert 方法在并发环境下是安全的。多个用户请求同时调用 ConvertToHTML 互不干扰，不需要加锁。
3. 代码整洁：隐藏了复杂的配置细节，外部调用时只需调用 ConvertToHTML(data) 即可，职责单一。