浏览器生成 ICO 文件:PNG 帧、256 尺寸和容器格式

2026-11-19 前端开发 有希 32 views

把一张 PNG 改后缀成 .ico,浏览器有时能显示,Windows 资源管理器却可能不认;做了多尺寸图标,任务栏还是糊;256 像素那一档明明生成了,打开却像空白。问题通常不在画布,而在 ICO 的容器结构:它不是“另一张图片”,而是一个带目录的文件,里面每一帧的尺寸、偏移和编码都要自己写对。本文按门户的纯前端实现,拆开 6 字节文件头、16 字节目录项和 256 尺寸写 0 的规则。

先给结论

ICO 文件由三部分组成:6 字节的 ICONDIR、每帧 16 字节的 ICONDIRENTRY、以及每帧的图片数据。现代图标可以直接内嵌 PNG,透明通道完整,不必手写 BMP 的 DIB 头和 AND 掩码。两个最容易写错的点:

  • 目录项的宽高字段各只有 1 字节,256 存不下,规范约定写 0。
  • 多尺寸不是把同一张图复制几份,而是每个尺寸单独重绘、单独编码,再按偏移拼进容器。

现象:浏览器能看,系统不认

现象常见原因
浏览器标签页能显示,Windows 图标是空白只是改了扩展名,容器结构不对
任务栏图标发虚只放了一个 32×32 或 48×48 帧
256 那一档打开是空白宽高字段写了 256,被截成 0 之外的值
透明区域变黑用了 JPEG 帧,或用了不带 alpha 的 BMP
多尺寸文件只显示最小一档目录项偏移或字节数写错,系统只读到第一帧

浏览器对图标的容错比 Windows 高。Chrome 可能直接按图片解码,所以“浏览器能显示”不能证明 ICO 容器合法。真正的验收要看文件结构和系统图标缓存。

容器结构:6 字节头 + 16 字节目录项

ICO 的多字节整数全部是小端。文件头只有三个字段:

偏移长度字段值
02reserved固定 0
22type1 表示图标
42count帧数

紧接着是 count 个目录项,每项 16 字节:

项内偏移长度字段说明
01width宽,256 写 0
11height高,256 写 0
21colorCount真彩写 0
31reserved固定 0
42planes固定 1
62bitCount通常写 32
84bytesInRes该帧数据字节数
124imageOffset该帧数据在文件中的偏移

目录项之后才是图片数据。偏移从文件开头算,第一帧的偏移等于 6 + 16 × 帧数。下面是核心组装代码:

const header = new ArrayBuffer(6 + 16 * frames.length)
const view = new DataView(header)

view.setUint16(0, 0, true) // reserved
view.setUint16(2, 1, true) // type = icon
view.setUint16(4, frames.length, true)

let offset = header.byteLength

frames.forEach((frame, index) => {
  const base = 6 + 16 * index
  const dimension = frame.size >= 256 ? 0 : frame.size

  view.setUint8(base, dimension) // width
  view.setUint8(base + 1, dimension) // height
  view.setUint8(base + 2, 0) // color count
  view.setUint8(base + 3, 0) // reserved
  view.setUint16(base + 4, 1, true) // planes
  view.setUint16(base + 6, 32, true) // bit count
  view.setUint32(base + 8, frame.data.byteLength, true)
  view.setUint32(base + 12, offset, true)

  offset += frame.data.byteLength
})

const blob = new Blob(
  [header, ...frames.map(frame => frame.data)],
  { type: 'image/x-icon' }
)

frame.data 是每个尺寸的 PNG 字节。DataView 的第三个参数 true 表示小端,漏掉它在大端机器或某些解析器上会读错。

256 为什么写成 0

宽高字段只有一个字节,最大值 255。ICO 规范把 0 定义为 256:不是“没有尺寸”,而是“这一档是 256×256”。如果直接 setUint8(base, 256),DataView 会按 ToUint8 截断成 0,看起来碰巧正确;但把判断写清楚,读代码的人才知道这不是遗漏。

const dimension = frame.size >= 256 ? 0 : frame.size

反过来,解析 ICO 时看到宽高为 0,要还原成 256,而不是当成空图。

用 PNG 帧还是 BMP 帧

维度PNG 帧BMP 帧
透明通道完整 alpha需要额外 AND 掩码
实现成本canvas.toBlob('image/png') 即可要写 DIB 头、像素行倒序、掩码对齐
体积通常更小256 尺寸明显更大
系统支持Windows Vista 起原生支持兼容更老的系统

门户选择全部内嵌 PNG。canvas.toBlob 的 MIME 固定为 image/png,目录项的 bitCount 仍写 32,表示每像素 32 位;系统读 PNG 帧时以 PNG 头里的尺寸和颜色信息为准。

function canvasToPng(canvas: HTMLCanvasElement): Promise<Blob> {
  return new Promise((resolve, reject) => {
    canvas.toBlob(
      blob => (blob ? resolve(blob) : reject(new Error('PNG 导出失败'))),
      'image/png'
    )
  })
}

如果目标环境必须支持 Windows XP 时代的图标解析,才需要退回 BMP + AND 掩码。对现在的 favicon 和快捷方式,PNG 帧足够。

多尺寸:不要放大,也不要用同一张图复制

门户默认生成 16、32、48、64、128、256 六档。每个尺寸都单独画到对应大小的画布,而不是把 256 的图缩小后重复使用。原图不够大时直接跳过该档:

function resolveSizes(sizes: number[], width: number, height: number, fit: 'cover' | 'contain') {
  const wanted = [...new Set(sizes)]
    .map(size => Math.min(size, 256))
    .sort((a, b) => a - b)

  // cover 要求两边都够大;contain 只要求最长边够
  const limit = fit === 'contain' ? Math.max(width, height) : Math.min(width, height)
  const usable = wanted.filter(size => size <= limit)

  return {
    targets: usable.length ? usable : [wanted[0]!],
    skipped: wanted.filter(size => size > limit)
  }
}

一张 100×50 的图,在 cover 模式下只有 16、32、48 三档可用,64 及以上会被跳过;在 contain 模式下最长边 100,64 也能放下,128 和 256 跳过。一个都不满足时退回最小档,保证至少产出一个图标,而不是直接失败。

cover 和 contain 的缩放公式

const scale = fit === 'contain'
  ? Math.min(size / sourceWidth, size / sourceHeight)
  : Math.max(size / sourceWidth, size / sourceHeight)

const drawWidth = Math.max(1, Math.round(sourceWidth * scale))
const drawHeight = Math.max(1, Math.round(sourceHeight * scale))
const offsetX = Math.round((size - drawWidth) / 2)
const offsetY = Math.round((size - drawHeight) / 2)

cover 取较大的缩放比,画布外的部分自动裁掉,适合照片和方形 Logo;contain 取较小的缩放比,四周留白,适合不能裁切的长图。留白默认透明,也可以指定填充色。

大图直接缩到 16 像素会出现锯齿和摩尔纹,所以绘制前先逐级对半缩小,直到接近目标尺寸再一次性画到画布。这一步比换插值算法更有效,也更容易验证。

验证:看文件头,不要只看预览

生成后先确认容器:

file public/favicon.ico
xxd -l 96 public/favicon.ico

file 应该识别为 MS Windows icon resource,并列出图标数量和尺寸。xxd 的前 6 字节应类似:

00000000: 0000 0100 0600

含义是 reserved 0、type 1、6 帧。接着的目录项里,16×16 帧的宽高字节是 10 10,256 帧的宽高字节是 00 00。如果 256 帧的目录项显示 00 00,但文件里没有对应的 PNG 数据,系统仍然会显示空白,所以要同时核对 bytesInRes 和 imageOffset 是否落在文件范围内。

检查项期望
文件类型MS Windows icon resource
帧数与目录项 count 一致
256 帧宽高目录项为 00 00,PNG 头为 256×256
每帧偏移等于前一帧偏移加字节数,首帧为 6 + 16 × 帧数
总长度最后一帧偏移加字节数等于文件大小

浏览器验收时,除了标签页 favicon,还要看任务栏和桌面快捷方式。系统有图标缓存,替换后可能需要重新登录或清理缓存才能看到新图标。

边界与坑

不要用 JPEG 做 ICO 帧。 JPEG 没有 alpha,透明区域会变黑或变白。ICO 内嵌 PNG 才有完整透明通道。

MIME 用 image/x-icon。 image/vnd.microsoft.icon 也常见,但下载和 Blob 场景下 image/x-icon 兼容性更稳。

256 不是唯一档位。 只放 256,任务栏和标签页会缩小使用,边缘发虚;只放 16,高分屏会放大。多档并存让系统自己挑。

目录项顺序建议从小到大。 不是强制,但便于调试,也和多数工具的输出一致。门户按尺寸升序写入。

不要无限加大画布。 浏览器能承受的尺寸有限,超大图还会触发内存问题。门户的画布边长上限是 8192,超过的拼版会整体缩小。

改扩展名不等于转格式。 .png 改名 .ico 后,文件头仍然是 PNG。浏览器可能容错,Windows 不会。

相关工具

把原图直接拖进 ICO 图标生成工具,可以一次导出多档尺寸并下载容器文件;需要先裁成正方形,可以先用 图片裁切工具;要换 PNG/WebP 等格式,再用 图片格式转换工具。更多浏览器本地处理图片的记录放在 技术笔记。

FAQ

为什么 ICO 里要放多个尺寸?

不同场景取的尺寸不同:浏览器标签页常用 16 或 32,任务栏和桌面快捷方式可能取 48、64 或 256。多档并存时系统会挑最合适的一档,避免放大或缩小导致发虚。

256×256 的宽高为什么写成 0?

目录项的宽高各占 1 字节,最大只能表示 255。规范把 0 定义为 256,所以写 0 不是漏填,而是 256 的约定写法。

内嵌 PNG 的 ICO 能在旧系统用吗?

Windows Vista 及以后支持 PNG 帧。更老的系统只认 BMP 帧,需要额外写 DIB 头和 AND 掩码。现在做 favicon 和普通桌面图标,PNG 帧足够。

原图不够 256 像素怎么办?

不要放大。放大只会更模糊,门户会跳过超过原图尺寸的档位,只生成可用的几档;如果一档都不满足,退回最小档保证有输出。

ICO 的难点不在图像处理,而在容器字段。把 6 字节头、16 字节目录项、256 写 0 和帧偏移这四件事固定下来,再用 file 和 xxd 验一次,浏览器和系统看到的就是同一个文件。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles