Go gif.DecodeAll 怎么读取 GIF 帧与延迟

在 Go 中读取动态 GIF，直接调用 gif.Decode 只能拿到第一张图；要取得全部动画帧和每帧停留时间，应使用 gif.DecodeAll。它返回 *gif.GIF，其中 Image[i] 与 Delay[i] 按相同下标对应，延迟单位是百分之一秒，因此换算为 time.Duration 时要乘 10*time.Millisecond。

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

从只读第一帧切换到 DecodeAll

旧写法常用 gif.Decode，它适合只要封面或静态预览的场景，因为返回类型是 image.Image，不会暴露后续帧和帧间延迟。动画分析、拆帧、生成缩略序列或自定义播放调度都需要改用 gif.DecodeAll。

package main

import (
    "fmt"
    "image/gif"
    "os"
    "time"
)

func main() {
    file, err := os.Open("animation.gif")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    animation, err := gif.DecodeAll(file)
    if err != nil {
        panic(err)
    }

    fmt.Printf("frames=%d loop=%d\n", len(animation.Image), animation.LoopCount)
    for i, frame := range animation.Image {
        delay := time.Duration(animation.Delay[i]) * 10 * time.Millisecond
        fmt.Printf("frame=%d bounds=%v delay=%s\n", i, frame.Bounds(), delay)
    }
}

判断是否读取成功，先检查 err，再看 len(animation.Image)。遍历时以 Image 为主，并用同一个下标读取 Delay；这样帧对象和显示时长不会错位。

理解 GIF 返回对象中的帧与延迟

gif.GIF 不只包含帧数组。Image 的元素类型是 *image.Paletted；Delay 为每帧保存一个整数；LoopCount 描述动画重复方式；Disposal 保存逐帧处置方法；Config 则包含逻辑画布的宽高和全局颜色模型信息。

最容易写错的是延迟单位。假设 Delay[i] == 8，它表示 8 个百分之一秒，也就是 80 毫秒，而不是 8 毫秒。通用换算式如下：

delay := time.Duration(animation.Delay[i]) * 10 * time.Millisecond

如果后续库要求秒数，可以使用 delay.Seconds()；若自己写定时器，直接保留 time.Duration 更不容易丢失精度。

读取元数据时注意帧边界和循环规则

每帧的 Bounds() 不一定都等于整个逻辑画布。GIF 可以只记录局部变化区域，处置方式还会影响下一帧显示时应该保留、清空还是恢复什么内容。因此，逐帧导出 Image[i] 可以获得解码后的调色板帧，但若目标是还原播放器最终看到的完整画面，还要结合 Config、帧边界与 Disposal 做合成，不能只把每个局部矩形直接当作完整截图。

LoopCount 也有明确语义：0 表示无限循环，-1 表示每帧只展示一次，其他值表示在首次播放之外再重新开始指定次数。读取工具可以原样保留该字段，不要把零误判为“不循环”。

不可信 GIF 先检查尺寸再解码全部帧

DecodeAll 会为帧分配调色板像素缓冲，并把所有已解码帧保留在内存中。处理用户上传或网络取得的 GIF 时，先用 DecodeConfig 读取逻辑宽高并设置上限，能够在完整解码前拒绝明显异常的尺寸。

DecodeConfig 会消耗 io.Reader 的数据，因此不能在同一个不可回退的 Reader 上接着直接调用 DecodeAll。简单做法是先把受控大小的数据读入字节切片，然后分别创建两个 bytes.Reader：

cfg, err := gif.DecodeConfig(bytes.NewReader(data))
if err != nil {
    return err
}
if cfg.Width > 4096 || cfg.Height > 4096 {
    return fmt.Errorf("GIF dimensions are too large: %dx%d", cfg.Width, cfg.Height)
}

animation, err := gif.DecodeAll(bytes.NewReader(data))
if err != nil {
    return err
}

尺寸检查只能限制单帧画布规模。业务仍应同时限制上传文件大小，并根据场景限制可接受的帧数或总处理成本；因为 DecodeAll 的设计目标就是返回完整动画，而不是流式释放前面的帧。

常见问题

问：为什么使用 gif.Decode 只能得到一帧？
Decode 的契约就是返回 GIF 中第一张嵌入图像；读取动画要换成 DecodeAll。

问：Delay 数值 5 是 5 毫秒吗？
不是。它表示 5 个百分之一秒，也就是 50 毫秒。

问：可以只遍历 Delay 而不看 Image 吗？
可以做时长统计，但处理帧内容时应按相同下标同时读取 Image[i] 与 Delay[i]。

问：LoopCount 为 0 为什么动画仍会重复？
因为在 gif.GIF 中，零表示无限循环，而不是播放零次。