anywebp

README

AnyWebP

简体中文 | English

把任意格式的图片，转换成体积最小的 WebP。

觉得有用的话，点击上方 ⭐ Star 按钮支持一下～

---

这是什么

AnyWebP 是一个面向桌面端的 Go 语言 WebP 转换库（附带命令行工具）：把 JPEG / PNG / GIF / BMP / TIFF / WebP / HEIC 等常见格式图片，一行代码转换成 WebP —— 目前压缩率最优的主流图片格式之一。

默认采用近无损模式：肉眼无法分辨画质差异，体积通常只有原图的 10%～20%。

实测效果（真实设计稿图片）：

文件	原始体积	转换后	节省
手绘卡片框 PNG	1.91 MB	311.6 KB	-84.1%
图标预览 PNG	531.3 KB	43.6 KB	-91.8%
网站图标 PNG	144.1 KB	25.1 KB	-82.6%

特性

• 全格式输入：JPEG / PNG / GIF（取首帧）/ WebP（再压缩）/ BMP / TIFF / HEIC·HEIF*
• 三种压缩模式
  • 近无损（默认）：视觉无损，体积最优，适合照片与设计稿
  • 严格无损：像素逐位还原，适合截图、Logo、线稿
  • 自定义有损：质量 1-100 自由控制
• 安全可靠：解码前做像素尺寸检查，防御解压炸弹；重新编码天然剥离 EXIF / GPS 等全部元数据
• 半透明精确处理：内部以非预乘 RGBA 直通编码器，无损模式下半透明像素也逐位一致
• 可选缩放：一行配置限制最长边，等比缩小（CatmullRom 高质量插值）
• 命令行工具：单文件、批量、整目录递归转换，自带体积统计

* HEIC / HEIF 依赖系统工具：macOS 自带 sips 开箱即用；Linux / Windows 安装 libheif（heif-convert）即可。

安装

库（要求 Go 1.25+，依赖 CGO，需本机有 C 编译器）：

go get github.com/crispvibe/anywebp

命令行工具：

go install github.com/crispvibe/anywebp/cmd/anywebp@latest

快速上手

一行转换

package main

import (
    "os"

    "github.com/crispvibe/anywebp"
)

func main() {
    data, _ := os.ReadFile("photo.jpg")

    // nil 选项 = 默认近无损模式
    webpBytes, err := anywebp.Convert(data, nil)
    if err != nil {
        panic(err)
    }
    os.WriteFile("photo.webp", webpBytes, 0644)
}

三种模式

// 近无损（默认）：视觉无损 + 最优体积
out, _ := anywebp.Convert(data, &anywebp.Options{Mode: anywebp.ModeNearLossless})

// 严格无损：像素逐位还原
out, _ = anywebp.Convert(data, &anywebp.Options{Mode: anywebp.ModeLossless})

// 自定义质量有损
out, _ = anywebp.Convert(data, &anywebp.Options{Mode: anywebp.ModeLossy, Quality: 70})

限制尺寸 / 文件与流式接口

// 最长边超过 2560px 时等比缩小
out, _ := anywebp.Convert(data, &anywebp.Options{MaxDimension: 2560})

// 文件 → 文件（dst 传空串自动生成同名 .webp，返回实际输出路径）
outPath, _ := anywebp.ConvertFile("photo.heic", "", nil)

// io.Reader → io.Writer
_ = anywebp.ConvertReader(reader, writer, nil)

// 已解码的 image.Image → WebP 字节
out, _ = anywebp.ConvertImage(img, nil)

// 嗅探格式（jpeg / png / gif / webp / bmp / tiff / heic）
format, _ := anywebp.DetectFormat(data)

命令行用法

anywebp photo.jpg                    # 近无损转换，输出 photo.webp
anywebp -lossless logo.png           # 严格无损
anywebp -q 70 banner.png             # 质量 70 有损
anywebp -max 2560 -o out/ ./photos   # 整目录批量转换并限制最长边
anywebp -r ./gallery                 # 递归处理子目录

输出示例：

  完成  photos/a.png → out/a.webp（1.91 MB → 311.6 KB，-84.1%）
  完成  photos/b.png → out/b.webp（531.3 KB → 43.6 KB，-91.8%）

共 2/2 个文件转换成功，总体积 2.43 MB → 355.2 KB（节省 85.7%）

API 一览

函数	说明
Convert(data []byte, opt *Options) ([]byte, error)	字节 → WebP 字节
ConvertFile(src, dst string, opt *Options) (string, error)	文件 → 文件，dst 为空自动命名
ConvertReader(r io.Reader, w io.Writer, opt *Options) error	流式转换
ConvertImage(img image.Image, opt *Options) ([]byte, error)	已解码图像 → WebP 字节
DetectFormat(data []byte) (string, error)	嗅探图片格式

Options 字段：

字段	类型	默认	说明
Mode	Mode	ModeNearLossless	压缩模式
Quality	float32	80	有损质量（仅 ModeLossy 生效）
MaxDimension	int	0（不缩放）	最长边上限（像素）
Exact	bool	false	无损时保留全透明像素的 RGB 值

常见问题

Q：为什么默认是「近无损」而不是「无损」？ 照片类图片严格无损通常只能省 30%～50%，而近无损（质量 95 的高保真有损）肉眼无法区分，却能省 80%～90%。对截图 / Logo / 线稿这类需要逐位还原的内容，请显式使用 ModeLossless。

Q：动图（GIF / 动态 WebP）怎么处理？ 当前版本取首帧转换为静态 WebP。动画转换在路线图中。

Q：为什么需要 CGO？ WebP 编码使用 chai2010/webp，它内置了 libwebp 的 C 源码，无需安装系统库，但编译时需要本机有 C 编译器（macOS 装 Xcode 命令行工具、Linux 装 gcc、Windows 装 MinGW 即可）。

Q：16 位深度的 PNG / TIFF 会怎样？ 会降到 8 位通道（WebP 格式本身的上限），属于格式约束而非实现限制。

路线图

• 动画 GIF → 动画 WebP
• AVIF 输入（纯 Go 解码）
• 真 near-lossless（libwebp -near_lossless 参数直通）
• 并发批量管线 API

贡献者

@crispvibe（Anna）· 作者与维护者

欢迎提交 Issue / PR，所有贡献者都会出现在 Contributors 页面。

开源协议

MIT © 禾屿科技

Documentation

Overview

Package anywebp 把任意常见格式的图片转换为 WebP。

特性一览：

• 输入格式：JPEG / PNG / GIF（取首帧）/ WebP / BMP / TIFF / HEIC·HEIF（依赖系统工具）；
• 三种压缩模式：近无损（默认，视觉无损且体积小）、严格无损、自定义质量有损；
• 可选最长边缩放，自动剥离 EXIF 等全部元数据（重新编码天然实现）；
• 解码前做像素尺寸安全检查，防御解压炸弹。

快速上手：

webpBytes, err := anywebp.Convert(jpegBytes, nil) // nil 使用默认近无损模式

更多用法见 README。

Index

• Constants
• Variables
• func Convert(data []byte, opt *Options) ([]byte, error)
• func ConvertFile(src, dst string, opt *Options) (string, error)
• func ConvertImage(img image.Image, opt *Options) ([]byte, error)
• func ConvertReader(r io.Reader, w io.Writer, opt *Options) error
• func DetectFormat(data []byte) (string, error)
• type Mode
• type Options

Constants

const (
	// DefaultLossyQuality ModeLossy 模式的默认质量。
	DefaultLossyQuality = 80
)

默认参数常量。

Variables

var (
	// ErrUnsupportedFormat 输入不是可识别的图片格式，或内容已损坏。
	ErrUnsupportedFormat = errors.New("anywebp: 不支持的图片格式或文件已损坏")
	// ErrImageTooLarge 图片像素尺寸超出安全上限。
	ErrImageTooLarge = errors.New("anywebp: 图片像素尺寸超出安全上限")
	// ErrEmptyInput 输入内容为空。
	ErrEmptyInput = errors.New("anywebp: 输入内容为空")
)

对外错误定义，调用方可用 errors.Is 判断。

Functions

func Convert

func Convert(data []byte, opt *Options) ([]byte, error)

Convert 把任意支持格式的图片字节转换为 WebP 字节。

完整流程：

1. 嗅探格式（HEIC/HEIF 先经系统工具转为 PNG）；
2. DecodeConfig 检查像素尺寸（防解压炸弹）；
3. 完整解码（动图取首帧）；
4. 按需等比缩放；
5. 重新编码为 WebP（自动剥离全部元数据）。

func ConvertFile

func ConvertFile(src, dst string, opt *Options) (string, error)

ConvertFile 文件接口：读取 src 图片文件，转换后写入 dst。 dst 为空时自动取 src 同目录同名的 .webp 路径，返回实际输出路径。

func ConvertImage

func ConvertImage(img image.Image, opt *Options) ([]byte, error)

ConvertImage 把已解码的 image.Image 编码为 WebP 字节。 适合调用方自己持有 image.Image 的场景（如截图、绘图程序）。

func ConvertReader

func ConvertReader(r io.Reader, w io.Writer, opt *Options) error

ConvertReader 流式接口：从 r 读取任意格式图片，向 w 写出 WebP。

func DetectFormat

func DetectFormat(data []byte) (string, error)

DetectFormat 嗅探图片格式，返回小写格式名： jpeg / png / gif / webp / bmp / tiff / heic；无法识别返回 ErrUnsupportedFormat。

Types

type Mode

type Mode int

Mode 压缩模式。

const (
	// ModeNearLossless 近无损（默认）：
	// 使用高质量有损编码（quality=95），肉眼几乎无法分辨差异，
	// 但体积通常只有严格无损的 1/3 ~ 1/2，是「视觉质量 / 体积」的最优平衡。
	ModeNearLossless Mode = iota

	// ModeLossless 严格无损：像素逐位还原，适合截图、线稿、Logo 等场景。
	ModeLossless

	// ModeLossy 自定义质量有损：质量由 Options.Quality 决定。
	ModeLossy
)

type Options

type Options struct {
	// Mode 压缩模式，默认 ModeNearLossless。
	Mode Mode

	// Quality 有损质量（1-100），仅 ModeLossy 生效；0 表示使用 DefaultLossyQuality。
	Quality float32

	// MaxDimension 最长边上限（像素）。
	// 大于 0 时，超出的图片会等比缩小到该尺寸；0 表示不缩放。
	MaxDimension int

	// Exact 严格无损时是否保留全透明像素的原始 RGB 值。
	// 默认 false（透明区域 RGB 可被优化以减小体积）。
	Exact bool
}

Options 转换选项。传 nil 等价于 &Options{}（全部默认值）。