@imgly/background-removal 使用指南:在浏览器与 Node.js 中实现图片背景移除
@imgly/background-removal 使用指南:在浏览器与 Node.js 中实现图片背景移除
@imgly/background-removal(浏览器端)与 @imgly/background-removal-node(Node.js 端)是 background-removal-js 仓库发布的两个 npm 包,它们让开发者无需自建抠图服务、无需上传图片到第三方服务器,即可在本地完成基于 ONNX 神经网络的前景分割与背景移除。本文以仓库根目录 README.md 为主线,结合两个子包的 浏览器端文档、Node.js 端文档 及 源码,完整讲解安装、配置、模型选择、性能优化、资源自托管与底层实现原理,读完后你可以直接在自有项目中落地一套端到端的背景移除能力。
项目概览:一套代码,双端覆盖
仓库根目录 README 明确了项目的核心定位:直接在浏览器或 Node.js 环境中移除图片背景,无额外成本、无隐私顾虑。整个项目由两个 npm 包组成:
| 包名 | 运行环境 | 核心能力 |
|---|---|---|
@imgly/background-removal |
浏览器 | 在用户浏览器本地完成背景移除,模型与 WASM 运行时按需加载 |
@imgly/background-removal-node |
Node.js | 在服务端进程中完成背景移除,适合批处理、上传链路自动化等场景 |
两个包共享同一套 ISNet 系列 ONNX 模型(见 bundle/models),推理逻辑高度同源,但分别面向浏览器(onnxruntime-web + Canvas/OffscreenCanvas 编解码)与服务端(onnxruntime-node + sharp 编解码)两套运行环境。
关键特性
- 浏览器内完成全流程:整个背景移除过程都在用户浏览器中执行,利用本地设备算力,无需为每次抠图支付服务端费用,也不需要搭建专门的抠图服务(见 packages/web/README.md 的 Overview 章节)。
- 数据保护:图片与敏感信息始终停留在用户设备上,不向外部服务器传输,天然规避了数据隐私风险。
- 与 IMG.LY CE.SDK 生态集成:两个包均可无缝嵌入 IMG.LY 的创意 SDK 产品线,为编辑器类产品提供图像 matting 与背景移除能力。
适用场景
仓库文档明确指出该方案面向以下典型使用场景:
- 电商应用:实时为商品图移除背景,直接生成可用于平台展示的透明底图;
- 图像编辑应用:作为抠图/换背景能力增强用户体验;
- Web 端图形设计工具:在浏览器中完成素材背景分离,简化创作流程。
无论专业开发者还是个人爱好者,都可以借助 @imgly/background-removal 快速构建这类应用。
浏览器端快速上手
安装
按 packages/web/README.md 的说明,通过 npm 安装主包,同时需要安装 onnxruntime-web 作为 peer dependency:
npm install @imgly/background-removal onnxruntime-web@1.21.0-dev.20250206-d981b153d3
说明:README 中给出的 onnxruntime-web 为带日期后缀的开发版本;而当前仓库 packages/web/package.json 声明的 peerDependencies 为
onnxruntime-web: "1.21.0"(稳定版),packages/node/README.md 的 News 章节也提到已升级到稳定版 ONNX Runtime 1.21.0。生产环境请以实际安装的包为准,保证主包与运行时版本匹配。
最小使用示例
import imglyRemoveBackground from "@imgly/background-removal"
let image_src: ImageData | ArrayBuffer | Uint8Array | Blob | URL | string = ...;
imglyRemoveBackground(image_src).then((blob: Blob) => {
// 结果是一个 PNG 编码的 Blob,可转换为 URL 用作 HTMLImage.src
const url = URL.createObjectURL(blob);
})
注意:首次运行时,库会下载 WASM 运行时与 ONNX 模型文件,耗时取决于网络带宽,因此第一次调用会比后续调用明显更慢。下载完成的文件会被浏览器缓存,同时库内部还有一层模型缓存(init 被 lodash memoize 包装,相同配置只初始化一次,见 packages/web/src/api/v1.ts)。
浏览器端高级配置
库本身开箱即用,不需要任何配置。但通过可选的 Config 参数可以精细控制行为。完整字段如下(默认值取自 packages/web/src/schema.ts 的 zod schema):
type Config = {
publicPath: string; // 模型与 wasm 文件的公共路径。
// 默认: 'https://staticimgly.com/@imgly/background-removal-data/${PACKAGE_VERSION}/dist/'
debug: boolean; // 是否输出有用的 console 日志,默认 false
device: 'cpu' | 'gpu';// 执行设备;'gpu' 时在支持 WebGPU 的浏览器上使用 WebGPU,默认 'cpu'
model: 'isnet' | 'isnet_fp16' | 'isnet_quint8'; // 使用的模型,默认 'isnet_fp16'
output: {
format: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/x-rgba8' | 'image/x-alpha8'; // 输出格式,默认 'image/png'
quality: number; // 输出质量,默认 0.8
};
rescale: boolean; // 是否将蒙版放大回原图尺寸再合成输出,默认 true
proxyToWorker: boolean; // 是否将推理代理到 Web Worker,默认 false
fetchArgs: Record<string, any>; // 传给 fetch 的附加参数,默认 {}
progress: (key: string, current: number, total: number) => void; // 下载/计算进度回调
};
关于 output.type 的历史说明
浏览器端 README 中仍能看到 output.type: 'foreground' | 'background' | 'mask' 字段,但请以当前源码为准:从 packages/web/src/schema.ts 看,output 对象只包含 format 与 quality 两个字段。output.type 配置已在 v1.3.0 中被移除(见 packages/web/CHANGELOG.md 的 Removed 章节),现在通过独立的 removeBackground / removeForeground / segmentForeground 函数区分前景、背景与蒙版输出。
模型选择与体积权衡
模型文件以 Git LFS 形式存在于仓库 bundle/models 下,从其指针文件记录的字节数可以确认三个模型的真实体积:
| 模型 | 配置取值 | 体积(约) | 说明 |
|---|---|---|---|
isnet |
'large' |
~176 MB | 体积最大、精度最高的原始模型 |
isnet_fp16 |
'medium'(默认) |
~88 MB | 默认模型,float16 半精度 |
isnet_quint8 |
'small' |
~44 MB | 量化模型,体积最小,多数情况效果良好但偶尔有伪影 |
配置中的 'small' / 'medium' / 'large' 别名会通过 schema 的 preprocess 映射到上述模型名(见 packages/web/src/schema.ts)。README 建议:对体积敏感的场景选 small(约 40MB),默认场景用 medium(约 80MB)。
输出格式
输出格式支持 image/png、image/jpeg、image/webp,以及两种原始格式:
image/x-rgba8:8 位 RGBA 原始像素数据,image/x-alpha8:单通道 8 位 Alpha 蒙版。这两种格式的 Blob 通过MimeType附带width、height参数(见 packages/web/src/codecs.ts),适合需要自行处理像素的应用。quality参数(默认 0.8)在编码为 jpeg/webp 时生效。
性能优化:SharedArrayBuffer 与跨源隔离
背景移除的性能很大程度上取决于浏览器可用的特性集,其中最关键的是 SharedArrayBuffer(多线程 WASM 推理依赖它)。由于 SharedArrayBuffer 的安全要求,你需要为站点开启跨源隔离(cross-origin isolation),在响应头中设置:
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp'
从 packages/web/src/schema.ts 可以看到,当开启 debug 且站点未处于跨源隔离状态时,库会在控制台输出性能降级警告。线程数则取自 navigator.hardwareConcurrency(见 packages/web/src/capabilities.js),并通过 ort.env.wasm.numThreads 配置(见 packages/web/src/onnx.ts)。
资源预加载与下载进度监控
预加载全部资源
默认情况下模型与 WASM 是按需下载的。你可以调用 preload 在任何时刻一次性下载全部资源:
import removeBackground, { preload, Config } from '@imgly/background-removal';
const config: Config = ...;
preload(config).then(() => {
console.log("Asset preloading succeeded")
})
preload 的实现会读取 publicPath 下的 resources.json 元数据,并对其中登记的所有资源逐一下载(见 packages/web/src/resource.ts)。仓库中的 next-example 示例 即在页面挂载后立即调用 preload。
下载进度回调
由于首次运行需要下载较大体积的模型文件,库提供 progress 回调以便你展示进度:
let config: Config = {
progress: (key, current, total) => {
console.log(`Downloading ${key}: ${current} of ${total}`);
}
};
从源码看,进度事件分为两类(packages/web/src/resource.ts 与 packages/web/src/api/v1.ts):
- 下载阶段:
fetch:${key},例如fetch:models/isnet_fp16,按分块累计上报; - 计算阶段:
compute:decode、compute:inference、compute:mask、compute:encode四步流水线。
自定义资源托管(Custom Asset Serving)
模型与 WASM 文件默认由 IMG.LY 托管。生产环境强烈建议自行托管,一方面避免依赖第三方 CDN,另一方面资源可以与应用一起部署、走自己的缓存策略。
操作步骤(浏览器端):
- 从 IMG.LY CDN 下载与当前
@imgly/background-removal版本一致的@imgly/background-removal-data数据包(URL 形如https://staticimgly.com/@imgly/background-removal-data/YOUR_PACKAGE_VERSION/package.tgz),解压; - 将解压后
package/dist目录中的内容放到你的静态资源目录(如/public)下; - 通过
publicPath指向该目录:
import imglyRemoveBackground, {Config} from "@imgly/background-removal"
const public_path = "https://example.com/assets/"; // 资源被服务的路径
let config: Config = {
publicPath: public_path, // 指向 wasm 与模型文件
};
let image_src: ImageData | ArrayBuffer | Uint8Array | Blob | URL | string = ...;
imglyRemoveBackground(image_src, config).then((blob: Blob) => {
// 结果是 PNG 编码的 Blob
const url = URL.createObjectURL(blob);
})
资源分块机制:仓库通过 scripts/package-resources.mjs 将大文件按 4MB 分块打包,并生成 resources.json 元数据(每块含 sha256 哈希、名称、偏移区间与文件总大小)。加载时 resource.ts 按块并发 fetch,校验每块大小后合并为完整 Blob。这种设计(v1.3.0 引入,见 packages/web/CHANGELOG.md)显著改善了缓存命中率与下载续传体验。数据包内容清单见 packages/web-data/.resources.mjs:包含 onnxruntime-web 的 wasm/mjs 运行时与 bundle/models 下的三个模型。
如果你在 Vite/Vue 项目中,可以参考 packages/web-examples/vite-project/src/App.vue 的做法:把数据包放到
public/js目录,并用new URL(import.meta.url)动态构造publicPath。
调试输出、CORS 与 fetchArgs
开启调试日志
let config: Config = {
debug: true
};
开启后会在控制台输出加载模型、WebGPU 使用情况、ort.env.wasm 配置、下载进度等详细信息(见 packages/web/src/onnx.ts 与 packages/web/src/schema.ts)。
CORS 与 fetchArgs
如果遇到 CORS 问题,可以通过 fetchArgs 给 fetch 传入附加参数:
let config: Config = {
fetchArgs: {
mode: 'no-cors'
}
};
fetchArgs 会作为第二参数原样传给 fetch(对应浏览器 Fetch API 的 RequestInit),用于携带自定义请求头、凭据等场景(见 packages/web/src/resource.ts 中的 fetch(url, config.fetchArgs))。
Node.js 端使用指南
@imgly/background-removal-node 面向服务端,可集成到批处理管道、上传处理中间件等场景。详见 packages/node/README.md。
安装与基本用法
npm install @imgly/background-removal-node
import {removeBackground} from "@imgly/background-removal-node";
// const {removeBackground} = require("@imgly/background-removal-node");
let image_src: Buffer | ArrayBuffer | Uint8Array | Blob | URL | string = ...;
removeBackground(image_src).then((blob: Blob) => {
// 结果是 PNG 编码的 Blob
})
Node 端输入类型支持 Buffer、ArrayBuffer、Uint8Array、Blob、URL 与文件路径字符串;字符串会被解析为绝对 URI(见 packages/node/src/utils.ts)。图片解码与编码由 sharp 完成(见 packages/node/src/codecs.ts)。
Node 端配置差异
type Config = {
publicPath: string; // 默认: `file://${path.resolve(`node_modules/@imgly/background-removal-node/dist/`)}/`
debug: boolean; // 默认 false
model: 'small' | 'medium'; // 默认 'medium',同样支持 'large'/'small'/'medium' 别名映射
output: {
format: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/x-rgba8' | 'image/x-alpha8'; // 默认 'image/png'
quality: number; // 默认 0.8
};
proxyToWorker: boolean; // 默认 true(与浏览器端相反)
fetchArgs: Record<string, any>;
progress: (key: string, current: number, total: number) => void;
};
与浏览器端相比,Node 端 schema(见 packages/node/src/schema.ts)没有 device 与 rescale 选项(服务端固定使用 CPU 推理,蒙版始终放大回原图尺寸),并且 publicPath 默认指向包内 dist 目录的 file:// URI,且会用 isURI 校验必须是合法 URI。Node 端同样支持 image/x-rgba8、image/x-alpha8 原始格式输出。
Node 端自定义资源托管
将包内 dist 目录的所有 .wasm 与 .onnx 文件复制到你的资源目录:
cp node_modules/@imgly/background-removal-node/dist/*.* $PUBLIC_PATH
然后重新配置 publicPath,既可以是本地文件路径,也可以是远程 HTTPS 地址:
import { removeBackground, Config} from "@imgly/background-removal-node"
const public_path = "file://${ASSET_PATH}"; // 本地文件系统路径
// const public_path = "https://example.com/assets/"; // 或者远程托管地址
let config: Config = {
publicPath: public_path,
};
let image_src: Buffer | ArrayBuffer | Uint8Array | Blob | URL | string = ...;
removeBackground(image_src, config).then((blob: Blob) => {
const url = URL.createObjectURL(blob);
})
Node 端的资源加载支持 file:、http:、https: 三种协议(见 packages/node/src/resource.ts),模型清单定义在 packages/node/.resources.mjs。
完整可运行的 Node 示例
仓库提供了可直接运行的示例 packages/node-examples/src/example_001.cjs,展示了 removeBackground + 进度回调 + 模型选择 + webp 输出的完整用法,并将结果写入本地 tmp/ 目录:
const { removeBackground } = require('@imgly/background-removal-node');
const fs = require('fs');
const uuidv4 = require('uuid').v4;
async function run() {
const config = {
debug: false,
progress: (key, current, total) => {
const [type, subtype] = key.split(':');
console.log(`${type} ${subtype} ${((current / total) * 100).toFixed(0)}%`);
},
model: 'isnet',
output: {
quality: 0.8,
format: 'image/webp' // 也支持 image/jpeg、image/png
}
};
const blob = await removeBackground('files/photo-1686002359940-hires.webp', config);
const buffer = await blob.arrayBuffer();
const format = config.output.format.split('/').pop();
const outFile = `tmp/${uuidv4()}.${format}`;
await fs.promises.mkdir('tmp', { recursive: true });
await fs.promises.writeFile(outFile, Buffer.from(buffer));
console.log(`Image saved to ${outFile}`);
}
run();
更多 API:前景移除、蒙版分割与蒙版复用
两个包都提供了比背景移除更细粒度的 API(浏览器端见 packages/web/src/api/v1.ts,Node 端见 packages/node/src/index.ts):
| 函数 | 行为 |
|---|---|
removeBackground(image, config?) |
移除背景,保留前景(alpha = 模型输出的蒙版值) |
removeForeground(image, config?) |
移除前景,保留背景(alpha = 255 - 蒙版值,即反相) |
segmentForeground(image, config?) |
仅提取前景蒙版(白色前景 + 透明背景;浏览器端另有别名 alphamask) |
applySegmentationMask(image, mask, config?) |
将任意蒙版应用到任意图片——当蒙版尺寸与原图不一致时,会自动用双线性插值放大蒙版再合成(见 packages/web/src/api/v1.ts) |
applySegmentationMask 的典型用法是"一次分割、多次复用":先对高清原图分割得到蒙版,再将该蒙版批量应用到同一组图的多个尺寸版本(srcset),避免对每张缩略图重复推理。仓库的 next-example 与 vite-project 都演示了这一组合用法。
底层原理:一次抠图的完整调用链
结合源码可以还原一次 removeBackground 调用的完整流水线:
- 配置校验:
validateConfig通过 zod schema 解析并填充默认值(packages/web/src/schema.ts),并用 lodashmemoize按配置序列化结果缓存推理会话; - 资源加载:读取
publicPath/resources.json,按 4MB 分块并发下载模型与 WASM,合并校验后得到完整 Blob(packages/web/src/resource.ts); - 运行时初始化:按
device选择 onnxruntime-web 的 wasm 或 webgpu 后端,配置线程数与wasmPaths,创建InferenceSession(packages/web/src/onnx.ts); - 图片解码:浏览器端通过
createImageBitmap+ Canvas/OffscreenCanvas 转为 RGBA 的 ndarray(packages/web/src/codecs.ts); - 预处理:双线性插值缩放到 1024×1024,再经 HWC→BCHW 转换并按 mean=128,128,128]、std=[256,256,256] 归一化为 float32([packages/web/src/inference.ts);
- 模型推理:输入名为
input的张量,取output输出,得到 1024×1024 的 float32 蒙版,乘以 255 转回 uint8; - 后处理:默认将蒙版放大回原始图片尺寸(
rescale: true),再把蒙版值写入原图 RGBA 的 alpha 通道(data[4*i+3] = alphamask.data[i]); - 编码输出:按
output.format与quality编码为 Blob(PNG/JPEG/WebP 走 CanvasconvertToBlob,rgba8/alpha8 走带尺寸参数的原始 MIME)。
整个"解码 → 推理 → 合成蒙版 → 编码"的四步计算过程都会通过 progress 回调上报进度。Node 端流程基本一致,只是解码/编码改用 sharp,且推理固定为 CPU。
仓库结构速览
- packages/web:浏览器端包
@imgly/background-removal,含 src/api/v1.ts 主入口、schema.ts 配置、onnx.ts 运行时、inference.ts 推理、resource.ts 资源加载、codecs.ts 编解码; - packages/node:Node.js 端包
@imgly/background-removal-node,结构与 web 端对应; - packages/web-data:数据包
@imgly/background-removal-data,打包 WASM 运行时与模型; - bundle/models:
isnet、isnet_fp16、isnet_quint8三个 ONNX 模型(LFS 存储); - packages/web-examples:Next.js 15 与 Vite/Vue 3 示例;
- packages/node-examples 与 packages/node-e2e:Node 端可运行示例与测试骨架;
- scripts:资源打包(4MB 分块)、changelog 生成、资源发布脚本。
仓库的 TODOS.md 还列出了演进方向(例如用 resolve 回调替代 publicPath、默认启用 GPU 等),可作为理解设计取舍的参考。
许可与作者
两个包均采用 AGPL 许可证 免费使用(仓库根目录 LICENSE.md),v1.4.0 起由 GPL 变更为 AGPL(见 packages/web/CHANGELOG.md)。如需其他授权选项,可联系 IMG.LY。该库由 IMG.LY 开发维护,其产品线还包括 CreativeEditor SDK、PhotoEditor SDK 与 VideoEditor SDK 等创意应用 SDK。