Go image/gif 怎么读取每帧 Delay 并保留动画循环次数

如果只调用 gif.Decode，拿到的只是 GIF 的第一帧；要保留动画的帧序、每帧停留时间和循环设置，应改用 gif.DecodeAll。它返回的 *gif.GIF 中，Image、Delay 按帧对应，Delay 的单位是百分之一秒，LoopCount 则记录播放循环语义。

本文把一个“只导出 GIF 元数据”的小任务拆开：先做尺寸保护，再读取所有帧，最后把结果整理成可写入 JSON 的结构。文章不讨论绘制、合成或修改动画。

从 Decode 迁移到 DecodeAll：先把首帧误区排除

旧代码常常从 Decode 开始，因为它能直接返回 image.Image。但这个 API 的契约就是返回第一张嵌入图，无法给出后续帧的 Delay 和循环信息。动画元数据读取应切换到 DecodeAll，它返回一个 gif.GIF：

先检查尺寸，再保留全部帧

DecodeAll 会为每一帧保留调色板图像，帧数、宽度和高度都会影响内存。处理不可信文件时，先用 DecodeConfig 读逻辑屏幕尺寸，再把文件指针移回开头，最后调用 DecodeAll：

package gifmeta

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

func decodeAll(path string) (*gif.GIF, error) {
    f, err := os.Open(path)
    if err != nil {
        return nil, fmt.Errorf("打开 GIF 失败: %w", err)
    }
    defer f.Close() // 文件句柄只在读取阶段使用，函数返回前统一关闭

    cfg, err := gif.DecodeConfig(f)
    if err != nil {
        return nil, fmt.Errorf("读取 GIF 尺寸失败: %w", err)
    }
    // 先限制逻辑屏幕尺寸，避免对异常大的输入直接分配全部帧缓冲。
    if cfg.Width  4096 || cfg.Height > 4096 {
        return nil, fmt.Errorf("GIF 尺寸超出允许范围: %dx%d", cfg.Width, cfg.Height)
    }
    if _, err := f.Seek(0, io.SeekStart); err != nil {
        return nil, fmt.Errorf("重置 GIF 文件位置失败: %w", err)
    }

    g, err := gif.DecodeAll(f)
    if err != nil {
        return nil, fmt.Errorf("读取 GIF 全部帧失败: %w", err)
    }
    return g, nil
}

这段代码的关键不是尺寸上限必须固定为 4096，而是把“检查尺寸”和“解码全部帧”分成两次读取，并在两次读取之间执行 Seek(0, io.SeekStart)。如果输入来自网络流而不是可定位文件，应先落盘或使用可重复读取的缓冲，再采用同样的顺序。

Delay 不是毫秒：按帧顺序转换成播放时长

Delay[i] 与 Image[i] 是同一帧的元数据。它的单位是百分之一秒，因此一个值为 12 的 Delay 表示约 120 毫秒，而不是 12 毫秒。导出时应使用同一个索引，并把单位转换写在代码里：

package gifmeta

import (
    "fmt"
    "time"

    "image/gif"
)

type FrameMeta struct {
    Index      int   `json:"index"`
    Delay      int   `json:"delay_1_100s"`
    DurationMS int64 `json:"duration_ms"`
}

func frameMetadata(g *gif.GIF) ([]FrameMeta, error) {
    if g == nil {
        return nil, fmt.Errorf("GIF 结果为空")
    }
    if len(g.Image) != len(g.Delay) {
        return nil, fmt.Errorf("帧数与 Delay 数量不一致: %d/%d", len(g.Image), len(g.Delay))
    }

    frames := make([]FrameMeta, 0, len(g.Image))
    for i, delay := range g.Delay {
        // GIF Delay 的单位是 1/100 秒；time.Second / 100 可避免手写毫秒常量。
        duration := time.Duration(delay) * (time.Second / 100)
        frames = append(frames, FrameMeta{
            Index:      i,
            Delay:      delay,
            DurationMS: duration.Milliseconds(),
        })
    }
    return frames, nil
}

保留原始 Delay 和转换后的 DurationMS 是比较稳妥的做法：原始字段方便以后重新编码 GIF，毫秒字段方便日志、接口或前端展示。不要把帧序交给 map，也不要在转换时重新排序。

LoopCount 的三种值要转换成文字语义

LoopCount 容易被理解成“总共播放几遍”，但 Go 的字段语义是动画被重新启动多少次：

• 0：无限循环。
• -1：每帧只显示一次，不重新启动动画。
• 其他非负值：动画额外重启该次数，因此总播放遍数是 LoopCount + 1。

导出接口时，建议同时保存原始数字和解释后的字段，避免调用方把 0 当成“没有循环”。

package gifmeta

func loopDescription(loopCount int) (string, int) {
    switch {
    case loopCount == 0:
        return "无限循环", 0 // 0 表示没有可计算的固定总遍数
    case loopCount == -1:
        return "只播放一次", 1 // -1 不重启动画，因此总遍数为 1
    default:
        return "固定播放", loopCount + 1 // 正数表示额外重启次数
    }
}

把帧信息和循环信息一起导出

下面的组合函数把前面的读取、帧转换和循环解释合并起来。JSON 标签保持稳定，适合被任务脚本或 HTTP 层直接编码：

package gifmeta

import (
    "fmt"
    "image/gif"
)

type AnimationMeta struct {
    FrameCount    int         `json:"frame_count"`
    LoopCount     int         `json:"loop_count"`
    LoopMeaning   string      `json:"loop_meaning"`
    TotalPlayings int         `json:"total_playings"`
    Frames        []FrameMeta `json:"frames"`
}

func exportMeta(g *gif.GIF) (*AnimationMeta, error) {
    frames, err := frameMetadata(g)
    if err != nil {
        return nil, err
    }
    meaning, total := loopDescription(g.LoopCount)
    if g.LoopCount == 0 {
        total = 0 // 0 表示无限，不伪造一个固定总遍数
    }
    return &AnimationMeta{
        FrameCount:    len(frames),
        LoopCount:     g.LoopCount,
        LoopMeaning:   meaning,
        TotalPlayings: total,
        Frames:        frames,
    }, nil
}

func validateGIF(g *gif.GIF) error {
    if g == nil || len(g.Image) == 0 {
        return fmt.Errorf("GIF 没有可导出的帧")
    }
    return nil
}

如果要写出 JSON，直接调用 json.NewEncoder 即可。JSON 本身不支持注释，因此不要把 Go 注释写进严格 JSON；字段含义应由结构体标签和接口文档说明。

迁移检查：这几处最容易读错

最终可以把读取流程固定为：DecodeConfig → 尺寸判断 → 重置读取位置 → DecodeAll → 按索引导出 Delay → 解释 LoopCount。这条链路只处理元数据和帧对象，不会把绘制逻辑混入导出任务。

相关问题

为什么 DecodeAll 后 Delay 可能是 0？

GIF 帧的 Delay 字段本身允许出现 0。导出层应保留原值，不要擅自把它改成一个业务默认值；如果播放器需要最小显示时长，应在播放策略层单独处理。

LoopCount 为 2 时到底播放几遍？

按 image/gif 的字段定义，2 表示额外重启两次，也就是总共播放 3 遍。接口字段最好同时提供原始值和“总遍数”字段。

只想读取尺寸时还需要 DecodeAll 吗？

不需要。只读宽高和全局颜色信息时使用 DecodeConfig，它不会解码全部帧；只有需要帧列表、Delay 或 LoopCount 时才继续调用 DecodeAll。