因image/draw仅做像素搬运，不处理字体渲染、alpha合成或颜色空间转换；文字水印须用freetype生成位图并正确设size（单位1/64磅）、dpi及基线坐标，否则发虚、偏移或黑块。
为什么直接用 image/draw.Draw 批量加水印会发虚、偏移或黑块
因为 image/draw 只做像素搬运，不处理字体渲染、alpha 合成或颜色空间转换。文字水印必须先生成位图，而 freetype.Face.Size 单位是「1/64 磅」——传 16 就等于 16/64 = 0.25 磅，几乎不可见；传 1024 则巨大溢出。常见错误还包括：没调 ctx.SetDPI(72) 导致尺寸失真，坐标用 y 而非 y + face.Metrics().Ascent.Round() 导致整体上移或截断。
- 文字水印必须用
freetype.ParseFont加载本地.ttf文件，别读系统路径（跨平台失效） - 每个
freetype.Context复用，不要在循环里反复 new - 叠加前检查水印图 bounds：
if wm.Bounds().Dx() == 0 || wm.Bounds().Dy() == 0，避免 panic - 目标矩形必须用
pt.Add(wm.Bounds().Size())动态算，别硬写宽高
image.Decode 报 invalid format 或 unknown format 怎么办
标准库默认只注册 image/png，JPEG/GIF 需显式导入解码器包，否则 image.Decode 直接返回 nil, err。更隐蔽的问题是：有些 JPG 实为 Exif 封装或 CMYK 编码，image/jpeg 拒绝解析。
- 必须加
import _ "image/jpeg"和import _ "image/png"（下划线不能少） - 优先用
image.Decode自动识别格式，而非硬写jpeg.Decode - 对可信源图片，可加
jpeg.WithDecodeConfig(true)绕过部分校验 - 顽固 case 改用
github.com/disintegration/imaging，它内置宽容 JPEG 解码器 - 批量前用
filepath.Ext(path)过滤后缀，避免误读非图文件
透明度失效、背景变黑、半透明变实心的根源
draw.Over 是 Porter-Duff 操作，但要求源图与目标图的 color.Model 兼容。常见错配：原图是 color.NRGBA，水印图却是 image.NewRGBA（alpha 默认全 0），或两者 alpha 位宽不同（如 NRGBA64 vs RGBA）。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 统一用
image.NewNRGBA创建水印画布（8-bit alpha，兼容性最好） - 绘制后手动设 alpha：
dst.SetNRGBA(x, y, color.NRGBA{r,g,b,128}) - 叠加改用
draw.DrawMask+draw.Over，传入 mask 图像 - JPEG 输出前必须合并 alpha：先
draw.Draw(dst, src.Bounds(), src, image.Point{}, draw.Src)，再贴水印
并发 OOM、goroutine 泛滥、CPU 打满怎么压
一张 4K PNG 解码后内存占用常超 30MB，千张图并发直接吃光内存。GOMAXPROCS 不限、无缓冲 channel、不缩放原图，是三大典型诱因。
- 用带缓冲 channel 控制并发数：
sem := make(chan struct{}, runtime.NumCPU()) - 批量前统一缩放主图（如宽高 ≤ 1200），用
golang.org/x/image/draw.ApproxBiLinear，别用CatmullRom（慢 5 倍） - 复用
*image.NRGBA缓冲池，按尺寸分类（如 small/medium/large），避免高频 GC - 水印图提前 decode 一次，全局复用，别每张图都重解
- 输出 WebP 时注意：
webp.Options{Lossless: false, Quality: 75}，别同时设Lossless: true和Quality
真正卡住的点往往不在算法，而在解码器注册缺失、alpha 未合并、bounds 写死、DPI 没设——这些细节不验证，跑通单张也没法批量。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
