image/draw.Draw不适合直接贴文字水印，因它仅做像素搬运，不处理字体渲染、alpha合成或颜色空间转换；文字水印必须先生成位图，否则必然发虚、偏移或出现黑块。
image/draw.Draw 不适合直接贴文字水印，它只做像素搬运，不处理字体渲染、alpha 合成或颜色空间转换。文字水印必须先生成位图，否则必然发虚、偏移或出现黑块。
为什么用 freetype 生成文字水印总糊或错位
核心问题出在 freetype.Face.Size 单位是「1/64 磅」，不是像素。传 16 实际是 16/64 = 0.25 磅，几乎不可见；传 1024 则远超画布尺寸，直接溢出。
常见错误还包括：
- 忘设 ctx.SetDPI(72) 或 96，导致字号换算失真
- 起始坐标没加 face.Metrics().Ascent.Round()，文字整体上浮或被截断
- 每次循环都 freetype.ParseFont，开销大且跨平台失败（系统字体路径不可靠）
实操建议：
- 提前加载 .ttf 文件并复用 freetype.Context
- 坐标计算统一用 x, y + ascent，避免凭感觉调参
- 所有文字绘制前，先用 face.GlyphBounds(rune) 验证单字宽度
批量合成时透明度失效或背景变灰
根本原因是 color.Model 不匹配：image.NewRGBA 默认 alpha 全为 0（完全透明），而 PNG 原图可能是 color.NRGBA；draw.Over 在模型不一致时会静默丢弃 alpha 通道。
典型现象：水印半透明变成全黑/全白，PNG 图片导出后带灰底或透明边。
实操建议：
- 水印画布统一用 image.NewNRGBA(bounds)（8-bit alpha，兼容性最好）
- 绘制完文字后，遍历像素显式设 alpha 值，例如 dst.SetNRGBA(x, y, color.NRGBA{0, 0, 0, 128})
- 叠加时改用 draw.DrawMask，传入 &image.Uniform{color.RGBA{0, 0, 0, 128}} 作 mask，比手动 blend 更稳
- 若原图含 CMYK 或非标准 EXIF，优先用 imaging.Open 替代 image.Decode，它内置宽容解码器
并发压缩+水印时 OOM 或 goroutine 泄漏
最常见翻车点：对每张图起一个 goroutine，1000 张图 = 1000 个 goroutine，每个解码 JPEG 占几 MB 内存，16G 机器瞬间卡死。
更隐蔽的问题是：image.Decode 静默返回 (nil, "jpeg", nil)（文件头损坏、EXIF 过长、CMYK 编码等），后续 imaging.Resize 直接 panic。
实操建议：
- 用固定数量 worker（如 4～8 个），通过带缓冲的 job chan 控制并发流
- 三值接收解码结果：img, format, err := image.Decode(f)，且 err == nil 后必须检查 img == nil
- 对 img == nil 的情况，先用 image.DecodeConfig 读 header 判断是否真为图像，再决定跳过或报错
- 加日志：log.Printf("skip %s: decode returned nil image, format=%q", path, format)
- PNG 批量处理务必避开 nfnt/resize 默认配置，它不保留 alpha，易炸出透明边或灰底
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
Thumbnail 和 Resize 在缩略图场景下的关键区别
imaging.Thumbnail 不是简单缩放：它先等比缩放到“不超过目标宽高”的尺寸，再居中裁切到精确尺寸（类似 CSS object-fit: cover）；而 imaging.Resize(w, h, img, filter) 是强制拉伸/填充，极易变形。
常见错误现象：头像压缩后脸被横向压扁，或背景被拉满失真。
使用建议：
- 生成头像、商品图等需固定尺寸的缩略图 → 用 imaging.Thumbnail
- 只限制最大宽度（如文章配图）→ 用 imaging.Resize(width, 0, img, filter)，高度传 0
- 需要填充背景色（如白底）→ 先 Resize，再用 imaging.Fill 裁切并垫色
- 水印叠加应在缩放后进行，否则小图上文字比例失调，大图上水印又过小
真正难的不是写通流程，而是把 freetype 的 DPI、Size、Ascent、Bounds 四个参数对齐，再让 draw.DrawMask 和 imaging.Thumbnail 在并发流里不出 race —— 这些细节不踩一遍坑，很难靠文档猜出来。
