安装

支持您选择的任意 JavaScript 包管理器。

谨慎

请确保您的包管理器已配置为安装可选依赖项

如果包管理器的锁定文件必须支持多个平台， 请参阅 跨平台 部分 以帮助决定使用哪个包管理器更合适。

npm install sharp

pnpm add sharp

yarn add sharp

bun add sharp

deno add --quiet npm:sharp
deno run --allow-env --allow-ffi --allow-read --allow-sys ...

先决条件

• Node-API v9 兼容运行时，例如 Node.js >= 20.9.0。

预编译二进制文件

为最常用的平台提供了预编译的 sharp 和 libvips 二进制文件：

• macOS x64 (>= 10.15)
• macOS ARM64
• Linux ARM (glibc >= 2.36)
• Linux ARM64 (glibc >= 2.28, musl >= 1.2.5)
• Linux RISC-V 64-bit (glibc >= 2.41)
• Linux ppc64 (glibc >= 2.36)
• Linux s390x (glibc >= 2.36)
• Linux x64 (glibc >= 2.28, musl >= 1.2.5, CPU with SSE4.2)
• Windows x64
• Windows x86 (已弃用，仅 Node.js 20)
• Windows ARM64
• FreeBSD (WebAssembly)

这为以下图像格式提供支持： JPEG、PNG、Ultra HDR、WebP、AVIF、TIFF、GIF 和 SVG（输入）。

跨平台

安装时，包管理器会自动针对当前操作系统平台和 CPU 架构选择预编译二进制文件（如果有可用）。

部分包管理器支持在同一安装树和/或使用同一锁定文件下，支持多平台和多架构。

npm v10+

谨慎

多平台共享的 npm package-lock.json 文件可能会因 npm 错误 #4828 导致安装问题

通过 --os、--cpu 和 --libc 标志提供有限支持。

要支持搭载 Intel x64 和 ARM64 CPU 的 macOS：

npm install --cpu=x64 --os=darwin sharp
npm install --cpu=arm64 --os=darwin sharp

当交叉目标为 Linux 时，必须指定 C 标准库。

要支持搭载 Intel x64 CPU 的 glibc（例如 Debian）和 musl（例如 Alpine）Linux：

npm install --cpu=x64 --os=linux --libc=glibc sharp
npm install --cpu=x64 --os=linux --libc=musl sharp

yarn v3+

使用 supportedArchitectures 配置。

pnpm v8+

使用 supportedArchitectures 配置。

自定义 libvips

若要使用自定义的全局安装版本 libvips 替代所提供的二进制文件， 请确保其版本至少为 package.json 中 config.libvips 标明的版本， 且可通过 pkg-config --modversion vips-cpp 定位。

有关编译 libvips 及其依赖的帮助，请参阅 从源代码构建 libvips。

在 Windows 平台及在 macOS 上通过 Rosetta 运行 Node.js 时，不支持使用全局安装的 libvips。

从源代码构建

npm install sharp
npm explore sharp -- npm run build

构建过程会查找全局安装的 libvips。 可以通过设置 SHARP_IGNORE_GLOBAL_LIBVIPS（绝不尝试使用它）或 SHARP_FORCE_GLOBAL_LIBVIPS（始终尝试使用它，即使缺失或过期） 环境变量来跳过此检测逻辑。

从源代码构建需要：

• C++17 编译器
• 版本 7 及以上的 node-addon-api
• 版本 9 及以上的 node-gyp 及其依赖

如果找不到 node-addon-api 或 node-gyp，请尝试通过以下方式添加：

npm install --save node-addon-api node-gyp

WebAssembly

通过 Workers 提供多线程 Wasm 的运行时环境可使用可选的 @img/sharp-wasm32 包。

npm install sharp @img/sharp-wasm32

• 不支持在 Web 浏览器中使用。
• 不支持在单线程环境中使用。
• 不支持原生文本渲染。
• 不支持 基于瓦片的输出。

Linux 内存分配器

大多数基于 glibc 的 Linux 系统 （例如 Debian、Red Hat）默认的内存分配器不适合长时间运行的多线程进程， 且涉及大量小内存分配。

因此，默认为防止碎片，sharp 在运行时检测到 glibc 分配器时 会限制线程基础的 并发 使用。

为帮助减少碎片并提升性能，推荐在这些系统使用替代的内存分配器，如 jemalloc。

使用 musl 的 Linux（如 Alpine）和非 Linux 系统不受影响。

AWS Lambda

The node_modules directory of the deployment package must include the binary files for the linux-x64 or linux-arm64 platform corresponding to the selected architecture.

When building a deployment package on a machine with a different architecture than the target, please refer to the Cross-platform section to help determine the appropriate package manager and configure it accordingly.

Some package managers use symbolic links, but AWS Lambda does not support symbolic links in deployment packages.

Another option is to use a well-maintained third-party Lambda Layer:

• cbschuld/sharp-aws-lambda-layer
• pH200/sharp-layer
• zoellner/sharp-heic-lambda-layer

For best performance, choose the largest memory available. A function with 1536 MB provides about 12 times the CPU time of a 128 MB function.

When integrating with AWS API Gateway, make sure the relevant Binary Media Types are configured.

打包工具

webpack

确保通过 externals 配置将 sharp 排除在打包之外。

externals: {
  'sharp': 'commonjs sharp'
}

esbuild

确保通过 external 配置将 sharp 排除在打包之外。

buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  platform: 'node',
  external: ['sharp'],
})

esbuild app.js --bundle --platform=node --external:sharp

对于 serverless-esbuild，确保通过 serverless.yml 配置安装特定平台的二进制文件。

custom:
  esbuild:
    external:
      - sharp
    packagerOptions:
      scripts:
        - npm install --os=linux --cpu=x64 sharp

electron

electron-builder

确保使用 asarUnpack 选项将 sharp 从 ASAR 归档文件中解包。

{
  "build": {
    "asar": true,
    "asarUnpack": [
      "**/node_modules/sharp/**/*",
      "**/node_modules/@img/**/*"
    ]
  }
}

electron-forge

确保使用 unpack 选项将 sharp 从 ASAR 归档文件中解包。

{
  "packagerConfig": {
    "asar": {
      "unpack": "**/node_modules/{sharp,@img}/**/*"
    }
  }
}

使用带有 Webpack 的 electron-forge 时， 您可能还需要添加 forge-externals-plugin。

vite

确保通过 build.rollupOptions 配置将 sharp 排除在打包之外。

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      external: [
        "sharp"
      ]
    }
  }
});

TypeScript

自 v0.32.0 版本起，TypeScript 类型定义作为 sharp 包的一部分发布。

早期版本通过 @types/sharp 包提供，现已弃用。

使用 TypeScript 时，请确保 devDependencies 中包含 @types/node 包。

字体

创建文本图像或渲染包含文本元素的 SVG 图像时， 使用 fontconfig 查找相关字体。

在 Windows 和 macOS 系统上，所有系统字体均可使用。

在使用 Homebrew 的 macOS 系统上，您可能需要将 PANGOCAIRO_BACKEND 环境变量设置为 fontconfig 以确保使用它进行字体查找，而非 Core Text。

在 Linux 系统上，通过包管理器安装且包含相关 fontconfig 配置的字体可用。

如果找不到 fontconfig 配置，将出现以下错误：

Fontconfig error: Cannot load default config file

在无法控制字体包的无服务器环境中， 请使用 FONTCONFIG_PATH 环境变量指向自定义路径。

嵌入式 SVG 字体不被支持。

已知冲突

Canvas 和 Windows

如果在同一个 Windows 进程中同时使用 canvas 和 sharp 模块，可能会发生以下错误：

The specified procedure could not be found.

Electron 和 Linux

Electron 提供的用于 Linux 的二进制文件会动态链接到全局安装的 glib，并将其符号泄漏到进程空间中，这可能导致出现以下错误：

GLib-GObject: g_object_ref: assertion 'G_IS_OBJECT (object)' failed
GLib-GObject: g_object_unref: assertion 'G_IS_OBJECT (object)' failed

请订阅 electron#46323 以获取更新。