Go image/gif.EncodeAll 怎么保留多帧动画的调色板

用 Go 的 gif.EncodeAll 导出多帧动画时，关键不是把多张 image.Image 直接塞进切片，而是先把每一帧转换成带调色板的 *image.Paletted。然后让 GIF.Image、Delay、Disposal 按相同帧数对齐；如果希望整段动画使用同一套颜色，就把同一个 color.Palette 同时用于每帧和全局 Config.ColorModel。

官方地址：https://pkg.go.dev/image/gif#EncodeAll

下面的例子只讨论帧调色板、播放间隔和清理策略，不评价 GIF 的主观画质，也不把静态说明图当作运行结果。

先把每帧变成 Paletted，再交给 EncodeAll

gif.GIF.Image 的元素类型是 *image.Paletted，因此 RGBA、NRGBA 或其他普通图像不能直接作为最终帧。工程上先选定一套可复用的调色板，再用量化绘制器把每个输入帧映射到这套颜色表，最后才组装 gif.GIF。

准备阶段：统一尺寸与颜色表，先限制输入边界

生产代码应先限制帧数量、宽高和内存预算。EncodeAll 负责写 GIF，并不会替业务决定不同尺寸的帧如何裁剪，也不会替调用方校验输入是否来自可信来源。下面的示例要求所有输入帧从 (0,0) 开始且尺寸相同；这样 Config.Width 和 Config.Height 能明确表达整段动画的画布边界。

统一调色板有两个好处：颜色索引的含义在不同帧之间稳定，生成的 GIF 结构也更容易审计。若业务确实需要每一帧独立颜色表，可以不给 Config.ColorModel 设置全局 palette，但必须仍然保证每一帧是有效的 Paletted，不能把“没有全局调色板”误解成“可以跳过帧调色板”。

最小实现：帧、Delay 和 Disposal 一起组装

下面的函数把输入帧转成共享 palette.Plan9，并把每帧间隔设为 8 个单位，即 80 毫秒。这里的延时只是示例配置；真实业务应由动画节奏或协议要求决定。LoopCount: 0 表示循环播放，若只想播放一次，应使用 -1。

package gifwriter

import (
    "fmt"
    "image"
    "image/color"
    "image/color/palette"
    "image/draw"
    "image/gif"
    "os"
)

func WriteAnimation(path string, sources []image.Image) (err error) {
    // 先限制帧数，避免调用方把无界输入一次性装进内存。
    if len(sources) == 0 || len(sources) > 120 {
        return fmt.Errorf("帧数必须在1到120之间")
    }

    // 所有帧共享这套调色板，保证颜色索引含义稳定。
    commonPalette := color.Palette(palette.Plan9)
    frames := make([]*image.Paletted, len(sources))
    delays := make([]int, len(sources))
    disposal := make([]byte, len(sources))
    var config image.Config

    for i, src := range sources {
        bounds := src.Bounds()
        if bounds.Min != (image.Point{}) {
            return fmt.Errorf("第%d帧的左上角必须是(0,0)", i)
        }
        if i == 0 {
            config = image.Config{
                ColorModel: commonPalette,
                Width:      bounds.Dx(),
                Height:     bounds.Dy(),
            }
        } else if bounds.Dx() != config.Width || bounds.Dy() != config.Height {
            return fmt.Errorf("第%d帧尺寸与第一帧不一致", i)
        }

        frame := image.NewPaletted(bounds, commonPalette)
        // 把普通图像量化到目标 palette；这一步不能省略。
        draw.FloydSteinberg.Draw(frame, bounds, src, image.Point{})
        frames[i] = frame
        delays[i] = 8
        // 不主动清除上一帧，适合完整画布帧的简单动画。
        disposal[i] = gif.DisposalNone
    }

    out, err := os.Create(path)
    if err != nil {
        return fmt.Errorf("创建 GIF 文件: %w", err)
    }
    defer func() {
        // 写入成功后仍要保留关闭文件的错误。
        if closeErr := out.Close(); err == nil {
            err = closeErr
        }
    }()

    data := &gif.GIF{
        Image:          frames,
        Delay:          delays,
        Disposal:       disposal,
        LoopCount:      0,
        Config:         config,
        BackgroundIndex: 0,
    }
    return gif.EncodeAll(out, data)
}

代码中 Image、Delay 和 Disposal 都按同一个索引表示第几帧。只设置 Image 而忘记延时数组，或者数组长度与帧数不一致，都会让动画结构变得难以维护。对完整画布帧，DisposalNone 是直观的默认选择；如果帧只包含局部变化，就要结合 GIF 播放器对背景清除或恢复前一帧的语义谨慎设置。

让每一帧的时间与清理策略对齐

Delay 的单位不是毫秒，而是百分之一秒；例如 8 表示 80 毫秒。Disposal 是逐帧字段，决定当前帧显示后如何处理画布。LoopCount 则属于整个动画，不应塞进逐帧数组。若使用全局调色板，Config 同时承担画布宽高、颜色模型和背景索引的边界说明。

在发布前，建议把检查项写成结构清单：帧数是否大于零；每帧 bounds 是否与 Config 一致；每个 palette 是否非空；len(Delay) 是否等于帧数；Disposal 若提供，长度是否也对齐；文件写入和关闭是否都返回错误。这里的清单用于工程审计，不代表本文已经运行了示例。

生产发布检查：不要用“只有一帧”掩盖数据组织错误

如果导出的文件看起来只有一帧，先回到数据结构检查，而不是立即更换编码库。常见原因是调用了 gif.Encode 而不是 gif.EncodeAll，或者组装时只 append 了第一帧；另一个常见问题是帧数组有多项，但业务在上游复用了同一块像素缓冲区，导致每一项最终呈现相同内容。

如果颜色异常，先确认每个 Paletted 使用了预期 palette，再确认是否把全局 Config.ColorModel 与每帧 palette 混用了。不要在错误路径里偷偷退回单帧编码，也不要只根据文件非空就判定成功。失败时保留原始错误、帧索引和尺寸信息，修复输入后重新生成整段动画。

对不可信图片输入，还应在解码阶段先读取尺寸并设置资源上限；EncodeAll 本身不是输入安全策略。写入文件后关闭 os.File，调用方再决定是否把这个文件交给上传或缓存流程。

常见问题

每帧必须使用同一套调色板吗？

不是必须。统一 palette 便于控制颜色索引和全局配置；如果每帧需要独立调色板，可以不设置全局 Config.ColorModel，但每帧仍必须是带 palette 的 *image.Paletted。

Delay 数组少于帧数可以吗？

不要依赖不完整数组表达业务语义。把它按帧数完整构造，缺省节奏也应由代码明确填入。

DisposalBackground 什么时候使用？

当下一帧需要把当前帧区域恢复为全局背景色时才考虑它，并同时正确设置 BackgroundIndex；完整画布动画通常不需要这种额外清理。

为什么不能用 Encode 写多帧？

gif.Encode 面向单个 image.Image，多帧动画应组装 gif.GIF 后调用 EncodeAll。

官方参考：gif.GIF 字段说明、image.Paletted。两张配图都是原创静态结构说明图，不是截图，也不是示例运行证据。