安装

与你选择的 JavaScript 包管理器配合使用。

¥Works with your choice of JavaScript package manager.

Caution

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

¥Please ensure your package manager is configured to install optional dependencies

如果包管理器锁定文件必须支持多个平台，请参阅 cross-platform 部分以帮助确定哪个包管理器合适。

¥If a package manager lockfile must support multiple platforms, please see the cross-platform section to help decide which package manager is appropriate.

npm install sharp

pnpm add sharp

使用 pnpm 时，你可能需要将 sharp 添加到 ignoredBuiltDependencies 以消除警告。

¥When using pnpm, you may need to add sharp to ignoredBuiltDependencies to silence warnings.

yarn add sharp

bun add sharp

deno run --allow-ffi ...

先决条件

¥Prerequisites

• Node-API v9 兼容运行时，例如 Node.js ^18.17.0 或 >=20.3.0。

  ¥Node-API v9 compatible runtime e.g. Node.js ^18.17.0 or >=20.3.0.

预构建的二进制文件

¥Prebuilt binaries

提供现成编译的 Sharp 和 libvips 二进制文件，可在最常见的平台上使用：

¥Ready-compiled sharp and libvips binaries are provided for use on the most common platforms:

• macOS x64 (>= 10.15)

• macOS ARM64

• Linux ARM (glibc >= 2.31)

• Linux ARM64（glibc >= 2.26，musl >= 1.2.2）

• Linux ppc64 (glibc >= 2.31)

• Linux s390x (glibc >= 2.31)

• Linux x64（glibc >= 2.26，musl >= 1.2.2，具有 SSE4.2 的 CPU）

  ¥Linux x64 (glibc >= 2.26, musl >= 1.2.2, CPU with SSE4.2)

• Windows x64

• Windows x86

这提供了对 JPEG、PNG、WebP、AVIF（仅限 8 位深度）、TIFF、GIF 和 SVG（输入）图片格式的支持。

¥This provides support for the JPEG, PNG, WebP, AVIF (limited to 8-bit depth), TIFF, GIF and SVG (input) image formats.

跨平台

¥Cross-platform

安装时，包管理器将自动为当前操作系统平台和 CPU 架构（如果可用）选择预构建的二进制文件。

¥At install time, package managers will automatically select prebuilt binaries for the current OS platform and CPU architecture, where available.

某些包管理器支持同一安装树中的多个平台和体系结构和/或使用相同的锁定文件。

¥Some package managers support multiple platforms and architectures within the same installation tree and/or using the same lockfile.

npm v10+

Caution

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

¥npm package-lock.json files shared by multiple platforms can cause installation problems due to npm bug #4828

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

¥Provides limited support via --os, --cpu and --libc flags.

要支持带有 Intel x64 和 ARM64 CPU 的 macOS：

¥To support macOS with Intel x64 and ARM64 CPUs:

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

当跨目标是 Linux 时，必须指定 C 标准库。

¥When the cross-target is Linux, the C standard library must be specified.

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

¥To support glibc (e.g. Debian) and musl (e.g. Alpine) Linux with Intel x64 CPUs:

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

yarn v3+

使用 supportedArchitectures 配置。

¥Use the supportedArchitectures configuration.

pnpm v8+

使用 supportedArchitectures 配置。

¥Use the supportedArchitectures configuration.

自定义 libvips

¥Custom libvips

要使用自定义的全局安装的 libvips 版本而不是提供的二进制文件，请确保它至少是 package.json 文件中 config.libvips 下列出的版本，并且可以使用 pkg-config --modversion vips-cpp 找到它。

¥To use a custom, globally-installed version of libvips instead of the provided binaries, make sure it is at least the version listed under config.libvips in the package.json file and that it can be located using pkg-config --modversion vips-cpp.

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

¥For help compiling libvips and its dependencies, please see building libvips from source.

在 Rosetta 下运行 Node.js 时，Windows 和 macOS 不支持使用全局安装的 libvips。

¥The use of a globally-installed libvips is unsupported on Windows and on macOS when running Node.js under Rosetta.

从源头构建

¥Building from source

该模块将在 npm install 时间从源代码编译，当时：

¥This module will be compiled from source at npm install time when:

• 检测到全局安装的 libvips，或者

  ¥a globally-installed libvips is detected, or

• 当使用 npm install --build-from-source 标志时。

  ¥when the npm install --build-from-source flag is used.

可以通过设置 SHARP_IGNORE_GLOBAL_LIBVIPS（从不尝试使用它）或 SHARP_FORCE_GLOBAL_LIBVIPS（始终尝试使用它，即使缺失或过时）环境变量来跳过检测全局安装的 libvips 的逻辑。

¥The logic to detect a globally-installed libvips can be skipped by setting the SHARP_IGNORE_GLOBAL_LIBVIPS (never try to use it) or SHARP_FORCE_GLOBAL_LIBVIPS (always try to use it, even when missing or outdated) environment variables.

从源代码构建需要：

¥Building from source requires:

• C++17 编译器

  ¥C++17 compiler

• node-addon-api version 7+

• node-gyp 版本 9+ 及其依赖

  ¥node-gyp version 9+ and its dependencies

安装时会检查这些依赖。如果找不到 node-addon-api 或 node-gyp，请尝试通过以下方式添加它们：

¥There is an install-time check for these dependencies. If node-addon-api or node-gyp cannot be found, try adding them via:

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

使用 pnpm 时，你可能需要将 sharp 添加到 onlyBuiltDependencies 以确保可以运行安装脚本。

¥When using pnpm, you may need to add sharp to onlyBuiltDependencies to ensure the installation script can be run.

对于交叉编译，可以使用 --platform、--arch 和 --libc npm 标志（或 npm_config_platform、npm_config_arch 和 npm_config_libc 环境变量）来配置目标环境。

¥For cross-compiling, the --platform, --arch and --libc npm flags (or the npm_config_platform, npm_config_arch and npm_config_libc environment variables) can be used to configure the target environment.

WebAssembly

为通过 Workers 提供多线程 Wasm 的运行时环境提供实验支持。

¥Experimental support is provided for runtime environments that provide multi-threaded Wasm via Workers.

不支持在网络浏览器中使用。

¥Use in web browsers is unsupported.

不支持原生文本渲染。

¥Native text rendering is unsupported.

基于图块的输出 不受支持。

¥Tile-based output is unsupported.

npm install --cpu=wasm32 sharp

FreeBSD

运行 npm install 之前必须安装 vips 软件包。

¥The vips package must be installed before npm install is run.

pkg install -y pkgconf vips

cd /usr/ports/graphics/vips/ && make install clean

Linux 内存分配器

¥Linux memory allocator

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

¥The default memory allocator on most glibc-based Linux systems (e.g. Debian, Red Hat) is unsuitable for long-running, multi-threaded processes that involve lots of small memory allocations.

因此，默认情况下，当运行时检测到 glibc 分配器时，sharp 将限制基于线程的 concurrency 的使用。

¥For this reason, by default, sharp will limit the use of thread-based concurrency when the glibc allocator is detected at runtime.

为了帮助避免碎片并提高这些系统的性能，建议使用替代内存分配器，例如 jemalloc。

¥To help avoid fragmentation and improve performance on these systems, the use of an alternative memory allocator such as jemalloc is recommended.

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

¥Those using musl-based Linux (e.g. Alpine) and non-Linux systems are unaffected.

AWS Lambda

部署包 的 node_modules 目录必须包含适用于 linux-x64 或 linux-arm64 平台的二进制文件，具体取决于所选架构。

¥The node_modules directory of the deployment package must include binaries for either the linux-x64 or linux-arm64 platforms depending on the chosen architecture.

在与目标体系结构不同的计算机上构建部署包时，请参阅 cross-platform 部分以帮助确定合适的包管理器以及如何配置它。

¥When building your deployment package on a machine that differs from the target architecture, see the cross-platform section to help decide which package manager is appropriate and how to configure it.

某些包管理器使用符号链接，但 AWS Lambda 在部署包中不支持这些链接。

¥Some package managers use symbolic links but AWS Lambda does not support these within deployment packages.

为了获得最佳性能，请选择最大的可用内存。1536 MB 函数提供的 CPU 时间比 128 MB 函数多大约 12 倍。

¥To get the best performance select the largest memory available. A 1536 MB function provides ~12x more CPU time than a 128 MB function.

与 AWS API Gateway 集成时，请确保其配置了相关的 二进制媒体类型。

¥When integrating with AWS API Gateway, ensure it is configured with the relevant binary media types.

打包器

¥Bundlers

webpack

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

¥Ensure sharp is excluded from bundling via the externals configuration.

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

esbuild

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

¥Ensure sharp is excluded from bundling via the external configuration.

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

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

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

¥For serverless-esbuild, ensure platform-specific binaries are installed via the serverless.yml configuration.

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

electron

electron-builder

确保使用 asarUnpack 选项从 ASAR 存档文件中解压 sharp。

¥Ensure sharp is unpacked from the ASAR archive file using the asarUnpack option.

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

electron-forge

确保使用 unpack 选项从 ASAR 存档文件中解压 sharp。

¥Ensure sharp is unpacked from the ASAR archive file using the unpack option.

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

将 electron-forge 与 Webpack 一起使用时，你可能还需要添加 forge-externals-plugin。

¥When using electron-forge with Webpack, you may also need to add forge-externals-plugin.

vite

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

¥Ensure sharp is excluded from bundling via the build.rollupOptions configuration.

import { defineConfig } from 'vite';

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

TypeScript

TypeScript 定义从 v0.32.0 开始作为 sharp 包的一部分发布。

¥TypeScript definitions are published as part of the sharp package from v0.32.0.

以前，这些可以通过 @types/sharp 软件包获得，但现已弃用。

¥Previously these were available via the @types/sharp package, which is now deprecated.

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

¥When using Typescript, please ensure devDependencies includes the @types/node package.

字体

¥Fonts

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

¥When creating text images or rendering SVG images that contain text elements, fontconfig is used to find the relevant fonts.

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

¥On Windows and macOS systems, all system fonts are available for use.

在使用 Homebrew 的 macOS 系统上，你可能需要将 PANGOCAIRO_BACKEND 环境变量设置为 fontconfig 值，以确保它用于字体发现而不是 Core Text。

¥On macOS systems using Homebrew, you may need to set the PANGOCAIRO_BACKEND environment variable to a value of fontconfig to ensure it is used for font discovery instead of Core Text.

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

¥On Linux systems, fonts that include the relevant fontconfig configuration when installed via package manager are available for use.

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

¥If fontconfig configuration is not found, the following error will occur:

Fontconfig error: Cannot load default config file

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

¥In serverless environments where there is no control over font packages, use the FONTCONFIG_PATH environment variable to point to a custom location.

不支持嵌入的 SVG 字体。

¥Embedded SVG fonts are unsupported.

已知冲突

¥Known conflicts

画布和窗户

¥Canvas and Windows

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

¥If both canvas and sharp modules are used in the same Windows process, the following error may occur:

The specified procedure could not be found.