Go image.NewPaletted 怎么为 GIF 帧准备调色板图像

做 GIF 动画时，如果只把每一帧当成普通的 image.Image，到了多帧容器这一步很容易卡住：GIF 的帧集合实际保存的是 []*image.Paletted。准备帧的关键不是先研究动画参数，而是先把“颜色”落成调色板索引，再交给 image.NewPaletted 创建的图像。

官方文档：https://pkg.go.dev/image#NewPaletted

本文只处理矩形、调色板、索引像素与 GIF 帧集合的关系，不展开调色板量化算法，也不讨论动画导出选项。读完后，你可以稳定创建一张适合 GIF 帧使用的 *image.Paletted。

先确认 GIF 帧为什么不是普通 RGBA 图像

我在整理多帧数据时，最初的直觉是用 image.NewRGBA 画完再直接塞进 GIF。单帧编码可以接受 image.Image，但 gif.GIF.Image 的字段类型是 []*image.Paletted。这说明多帧对象需要的不只是颜色值，还需要每个像素对应的调色板编号。

可以把一帧拆成三部分理解：Rect 描述画布范围，Palette 描述编号到颜色的表，Pix 保存每个位置的 uint8 索引。Stride 则告诉你从一行跳到下一行要跨多少个索引字节。这样看，NewPaletted 做的是准备一个“索引型画布”，不是替你完成颜色量化。

先把 GIF 帧拆成矩形、调色板和索引平面

创建帧时先固定矩形和调色板。调色板中的位置就是索引，下面的示例故意只放三种颜色，让索引关系一眼可见：

package main

import (
	"fmt"
	"image"
	"image/color"
)

func main() {
	// 调色板位置就是像素可写入的颜色索引，GIF 场景要控制在可接受的颜色数量内。
	p := color.Palette{
		color.Black,
		color.White,
		color.RGBA{R: 0x2f, G: 0x80, B: 0xed, A: 0xff},
	}
	// Rect 决定帧的宽高；NewPaletted 同时准备 Pix、Stride 和 Palette。
	frame := image.NewPaletted(image.Rect(0, 0, 160, 96), p)
	// 直接写入索引，而不是把 RGBA 数值塞进 Pix。
	frame.SetColorIndex(12, 8, 1)
	frame.SetColorIndex(80, 48, 2)

	// 用结构字段检查帧的形状，便于发现矩形或行跨度配置错误。
	fmt.Println(frame.Bounds().Dx(), frame.Bounds().Dy())
	fmt.Println(frame.Stride, len(frame.Pix), frame.ColorIndex(12, 8))
}

这里的 SetColorIndex 写入的是 1 和 2，读取时 ColorIndex 再拿到同样的编号。len(Pix) 与矩形面积、行跨度有关；不要把它当成 RGB 字节数组去切片。

把颜色转换成索引，再交给 GIF 帧集合

如果上游拿到的是 color.Color，不要手工猜索引。用同一份 color.Palette 调用 Index，再把返回值转换成 uint8 写入帧。这样“颜色选择”和“帧存储”保持同源：

func setNearestColor(frame *image.Paletted, x, y int, c color.Color) {
	// Palette.Index 按调色板寻找最接近的颜色，返回的是调色板位置。
	index := frame.Palette.Index(c)
	if index = len(frame.Palette) {
		// 这里保留显式保护，避免异常索引污染帧数据。
		return
	}
	// Paletted 的 Pix 使用 uint8 索引，写入前把 int 转成索引类型。
	frame.SetColorIndex(x, y, uint8(index))
}

Palette.Index 返回的是调色板中的位置，不是 RGB 值。帧和 GIF 容器使用的调色板边界也要统一：如果多个帧共享全局颜色表，帧中的索引必须能在这张表里解释；如果各帧自带颜色表，则每一帧的 Palette 都要随帧保留。

多帧结构可以先这样组织，重点是让每个元素都是 *image.Paletted，而不是把 RGBA 指针混进来：

g := &gif.GIF{
	// 每个元素都是已经准备好的 Paletted 帧。
	Image: []*image.Paletted{frame1, frame2},
	// Config 用来表达整体画布边界，帧矩形不能超出它。
	Config: image.Config{Width: 160, Height: 96, ColorModel: frame1.Palette},
}

上面的结构只是 GIF 数据的静态组织示意，真正导出时再交给对应编码接口。当前阶段先检查帧类型、调色板和画布边界，能比直接追查“为什么动画颜色错位”更快定位问题。

准备完成后只检查三件事

第一，帧的动态类型是 *image.Paletted，并且 GIF.Image 中没有混入普通 RGBA 帧。第二，所有写入的索引都小于对应调色板长度，颜色映射和像素存储使用的是同一份 Palette。第三，帧的 Bounds 位于 GIF 的 Config 画布内，尤其要留意非零起点矩形带来的边界差异。

如果只是想把一张普通图片转成 GIF，单帧编码器可以根据选项完成颜色转换；但在你自己维护多帧数组时，显式创建 Paletted 会让每帧的索引和调色板关系更可控。

常见误区与速查表

一句话记忆：NewPaletted 负责创建“矩形 + 调色板 + 索引像素”的帧容器；Palette.Index 负责把颜色找到编号；gif.GIF.Image 负责保存多帧。把这三层分开，GIF 帧准备就不会再和普通 RGBA 图像混为一谈。

相关问题

• 为什么 gif.Decode 只返回 GIF 的第一帧？因为它的接口语义就是读取第一幅嵌入图像，多帧读取应使用对应的多帧接口。
• Palette.Index 返回的是什么？返回调色板中与颜色最接近的元素位置，写入 Paletted 时再作为颜色索引使用。
• 每帧必须使用同一张调色板吗？不一定；是否共享全局颜色表由 GIF 组织方式决定，但每个索引都必须能在它所对应的 Palette 中解释。