@imgly/background-removal 使用指南:在浏览器与 Node.js 中实现图片背景移除

原创2026-10-14 10:40:231,616 阅读
文章标签:计算机视觉图像处理AI 应用

@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,另一方面资源可以与应用一起部署、走自己的缓存策略。

操作步骤(浏览器端):

  1. 从 IMG.LY CDN 下载与当前 @imgly/background-removal 版本一致的 @imgly/background-removal-data 数据包(URL 形如 https://staticimgly.com/@imgly/background-removal-data/YOUR_PACKAGE_VERSION/package.tgz),解压;
  2. 将解压后 package/dist 目录中的内容放到你的静态资源目录(如 /public)下;
  3. 通过 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 调用的完整流水线:

  1. 配置校验:validateConfig 通过 zod schema 解析并填充默认值(packages/web/src/schema.ts),并用 lodash memoize 按配置序列化结果缓存推理会话;
  2. 资源加载:读取 publicPath/resources.json,按 4MB 分块并发下载模型与 WASM,合并校验后得到完整 Blob(packages/web/src/resource.ts);
  3. 运行时初始化:按 device 选择 onnxruntime-web 的 wasm 或 webgpu 后端,配置线程数与 wasmPaths,创建 InferenceSession(packages/web/src/onnx.ts);
  4. 图片解码:浏览器端通过 createImageBitmap + Canvas/OffscreenCanvas 转为 RGBA 的 ndarray(packages/web/src/codecs.ts);
  5. 预处理:双线性插值缩放到 1024×1024,再经 HWC→BCHW 转换并按 mean=128,128,128]、std=[256,256,256] 归一化为 float32([packages/web/src/inference.ts);
  6. 模型推理:输入名为 input 的张量,取 output 输出,得到 1024×1024 的 float32 蒙版,乘以 255 转回 uint8;
  7. 后处理:默认将蒙版放大回原始图片尺寸(rescale: true),再把蒙版值写入原图 RGBA 的 alpha 通道(data[4*i+3] = alphamask.data[i]);
  8. 编码输出:按 output.format 与 quality 编码为 Blob(PNG/JPEG/WebP 走 Canvas convertToBlob,rgba8/alpha8 走带尺寸参数的原始 MIME)。

整个"解码 → 推理 → 合成蒙版 → 编码"的四步计算过程都会通过 progress 回调上报进度。Node 端流程基本一致,只是解码/编码改用 sharp,且推理固定为 CPU。

仓库结构速览

仓库的 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。

登录后查看全文
background-removal-js