安装

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

🌐 Works with your choice of JavaScript package manager.

Caution

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

如果一个包管理器锁文件必须支持多平台，请查看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

yarn add sharp

bun add sharp

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

先决条件

🌐 Prerequisites

• 兼容 Node-API v9 的运行环境，例如 Node.js >= 20.9.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.36）
• Linux ARM64（glibc >= 2.28，musl >= 1.2.5）
• Linux RISC-V 64位（glibc >= 2.41）
• Linux ppc64 (glibc >= 2.36)
• Linux s390x (glibc >= 2.36)
• Linux x64（glibc ≥ 2.28，musl ≥ 1.2.5，支持 SSE4.2 的 CPU）
• Windows x64
• Windows x86（已弃用，仅限 Node.js 20）
• Windows ARM64
• FreeBSD（WebAssembly）

这支持 JPEG、PNG、Ultra HDR、WebP、AVIF、TIFF、GIF 和 SVG（输入）图片格式。

🌐 This provides support for the JPEG, PNG, Ultra HDR, WebP, AVIF, 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 导致安装问题

通过 --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.

在 Windows 上，以及在 macOS 上通过 Rosetta 运行 Node.js 时，不支持使用全局安装的 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 sharp
npm explore sharp -- npm run build

构建过程会搜索全局安装的 libvips。可以通过设置环境变量来跳过此检测逻辑： SHARP_IGNORE_GLOBAL_LIBVIPS（永远不要尝试使用它）或 SHARP_FORCE_GLOBAL_LIBVIPS（即使缺失或过时也总是尝试使用它）。

🌐 The build process will search for a globally-installed libvips. This detection logic 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 编译器
• node-addon-api 版本 7+
• node-gyp 版本 9+ 及其依赖

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

🌐 If node-addon-api or node-gyp cannot be found, try adding them via:

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

WebAssembly

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

🌐 Runtime environments that provide multi-threaded Wasm via Workers are supported by the optional @img/sharp-wasm32 package.

npm install sharp @img/sharp-wasm32

• 不支持在网络浏览器中使用。
• 在单线程环境中不支持使用。
• 不支持原生文本渲染。
• 基于图块的输出 不被支持。

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 会限制基于线程的并发使用。

🌐 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.

另一种方法是使用维护良好的第三方 Lambda 层：

🌐 An alternative approach is to use a well-maintained, third-party Lambda Layer:

• cbschuld/sharp-aws-lambda-layer
• pH200/锐利层
• zoellner/sharp-heic-lambda-layer

为了获得最佳性能，请选择可用的最大内存。 一个 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 集成时，确保它已配置相关的binary media types。

🌐 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 --libc=glibc --cpu=x64 sharp

electron

electron-builder

确保通过 asarUnpack 选项将 sharp 从 ASAR 压缩文件中解压出来。

🌐 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 选项将 sharp 从 ASAR 压缩包中解压。

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

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

当在 Webpack 中使用 electron-forge 时，你可能还需要添加 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

从 v0.32.0 开始，TypeScript 定义作为 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 和 Windows

🌐 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.

Electron 和 Linux

🌐 Electron and Linux

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

🌐 Binaries provided by Electron for use on Linux dynamically link against a globally-installed glib and leak its symbols into the process space, which may cause the following error to occur:

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

Please subscribe to electron#46323 for updates.