浏览器生成 ICO 文件:PNG 帧、256 尺寸和容器格式
把一张 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 的多字节整数全部是小端。文件头只有三个字段:
| 偏移 | 长度 | 字段 | 值 |
|---|---|---|---|
| 0 | 2 | reserved | 固定 0 |
| 2 | 2 | type | 1 表示图标 |
| 4 | 2 | count | 帧数 |
紧接着是 count 个目录项,每项 16 字节:
| 项内偏移 | 长度 | 字段 | 说明 |
|---|---|---|---|
| 0 | 1 | width | 宽,256 写 0 |
| 1 | 1 | height | 高,256 写 0 |
| 2 | 1 | colorCount | 真彩写 0 |
| 3 | 1 | reserved | 固定 0 |
| 4 | 2 | planes | 固定 1 |
| 6 | 2 | bitCount | 通常写 32 |
| 8 | 4 | bytesInRes | 该帧数据字节数 |
| 12 | 4 | imageOffset | 该帧数据在文件中的偏移 |
目录项之后才是图片数据。偏移从文件开头算,第一帧的偏移等于 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 验一次,浏览器和系统看到的就是同一个文件。
评论
还没有评论,来说两句吧