安装

支持您选择的任意 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 compatible runtime e.g. 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 (deprecated, Node.js 20 only)
• Windows ARM64 (CPU with ARMv8.4 required for all features)
• FreeBSD (WebAssembly)

This provides support for the JPEG, PNG, Ultra HDR, WebP, AVIF, TIFF, GIF and SVG (input) image formats.

跨平台

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

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

npm v10+

谨慎

多平台共享的 npm package-lock.json 文件可能会因 npm bug #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

部署包的 node_modules 目录必须包含对应所选架构的 linux-x64 或 linux-arm64 平台的二进制文件。

当在与目标架构不同的机器上构建部署包时， 请参考跨平台 部分帮助确定合适的包管理器并进行配置。

部分包管理器会使用符号链接， 但 AWS Lambda 不支持部署包中的符号链接。

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

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

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

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

打包工具

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.