GIF 的 LoopCount 字段语义易被误解：设为 0 表示无限循环，设为 1 实际表示“循环 1 次额外播放”，即总共播放 2 遍；要实现严格单次播放，需将 LoopCount 设为 0 并配合浏览器兼容性处理或使用替代方案。
gif 的 `loopcount` 字段语义易被误解：设为 `0` 表示无限循环，设为 `1` 实际表示“循环 1 次额外播放”，即总共播放 2 遍；要实现严格单次播放，需将 `loopcount` 设为 `0` 并配合浏览器兼容性处理或使用替代方案。
在 Go 标准库 image/gif 中，gif.GIF.LoopCount 的行为遵循 GIF89a 规范：该字段存储的是循环次数（不包括首次播放）。也就是说：
- LoopCount = 0 → 无限循环（规范定义的默认值）
- LoopCount = 1 → 首次播放 + 再循环 1 次 = 共播放 2 遍
- LoopCount = 2 → 共播放 3 遍
- …以此类推
⚠️ 因此，标准 GIF 格式本身不支持“仅播放一次”的原生语义——它必须至少播放一遍，而“不再重复”是通过 LoopCount = 0（即省略循环控制块）隐式表达的。但问题在于：不同浏览器对缺失 NETSCAPE2.0 扩展块的解释不一致。
例如：
- Firefox 将无循环声明的 GIF 视为「播放一次后停止」；
- Chrome、Safari 和大多数现代浏览器则将其视为「无限循环」（回退到默认行为）。
✅ 正确做法是：显式写入 NETSCAPE2.0 应用扩展块，并将 LoopCount 设为 0 —— 这才是规范中表示“无限循环”的写法；而“仅播放一次”需反向操作：完全省略该扩展块。
但 image/gif.EncodeAll 在 LoopCount == 0 时仍会写入循环扩展块（Go issue #16522），导致无法规避。因此，可靠方案如下：
✅ 推荐解决方案：手动构造 GIF，跳过循环扩展块
package main
import (
"image"
"image/color"
"image/gif"
"os"
)
func main() {
// 构造单帧示例（实际应为多帧）
bounds := image.Rect(0, 0, 100, 100)
img := image.NewPaletted(bounds, color.Palette{color.White, color.Black})
for y := 0; y < 100; y++ {
for x := 0; x < 100; x++ {
if (x+y)%20 < 10 {
img.SetColorIndex(x, y, 1)
}
}
}
// 构建 GIF 结构体（关键：LoopCount = 0 且不调用 EncodeAll）
gifImg := &gif.GIF{
Image: []*image.Paletted{img},
Delay: []int{10}, // 单位：centiseconds（0.1 秒）
// 不设置 LoopCount —— 让 EncodeAll 默认不写入循环扩展块
// 或显式设为 0 并后续 patch（见下方说明）
}
f, _ := os.Create("once.gif")
defer f.Close()
// 使用 EncodeAll 时，若 LoopCount == 0，Go 仍会写入循环块
// 因此更稳妥方式：编码后手动移除 NETSCAPE2.0 扩展块（需二进制解析）
// ⚠️ 生产环境建议改用成熟库如 github.com/disintegration/gift 或直接用 ffmpeg
gif.EncodeAll(f, gifImg)
}? 替代方案（推荐用于生产）
- 使用 golang.org/x/image/gif 的 patched fork（社区已有修复 PR）
-
借助命令行工具生成（最稳定）：
# 使用 ImageMagick 创建真·单次 GIF（无循环声明） convert -delay 10 -loop 0 frame1.png frame2.png frame3.png once.gif # 注意：ImageMagick 的 `-loop 0` 表示无限循环；要单次播放，应： convert -delay 10 -loop 1 frame1.png frame2.png frame3.png once.gif # 错误！仍是2遍 # 正确做法：省略 -loop 参数（默认单次） convert -delay 10 frame1.png frame2.png frame3.png once.gif
-
前端兜底控制（适用于 Web 场景）：
<img src="once.gif" oncanplay="this.addEventListener('load', () => { setTimeout(() => this.src = this.src.split('?')[0] + '?t=' + Date.now(), /* 总动画时长 */ 300); })">或更可靠地，用 <canvas> 解析帧并手动控制播放。
✅ 总结
- GIF 格式没有“播放一次”原生标记；LoopCount = 1 ≡ 播放两遍；LoopCount = 0 ≡ 无限循环（且多数浏览器如此实现）。
- Go 标准库 gif.EncodeAll 无法生成真正单次 GIF；需手动干预二进制流或切换工具链。
- 开发建议：对强交互场景，优先使用 CSS 动画 + PNG 序列或 WebP（支持精确播放次数）；GIF 仅作降级兼容。
