安装 - sharp中文文档

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

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

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

npm install sharp

pnpm add sharp

yarn add sharp

# yarn v1 (maintenance mode)
Yarn add sharp --ignore-engines

bun add sharp

deno run --allow-ffi ...

先决条件

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

预构建的二进制文件

已编译的 sharp 和 libvips 二进制文件可用于最常见的平台：

MacOS x64 (>= 10.13)
MacOS ARM64
Linux ARM (glibc >= 2.28)
Linux ARM64 (glibc >= 2.26, musl >= 1.2.2)
Linux s390x (glibc >= 2.31)
Linux x64 (glibc >= 2.26, musl >= 1.2.2, CPU 带SSE4.2)
Windows x64
Windows x86

这为 JPEG、PNG、WebP、AVIF（限制为 8 位深度）、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文件中engines.libvips下列出的版本，并且可以使用pkg-config --modversion vips-cpp找到它。

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

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

从源代码构建

如果出现以下情况，npm 安装此模块时将从源代码进行编译：

检测到全局安装的 libvips，或
使用 npm install --build-from-source 标志时。

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

从源代码构建需要：

C++11 编译器
Node-addon-apiVersion 7+
Node-gypVersion 9+ 及其依赖项

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

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

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

WebAssembly

通过 Workers 实验性地支持多线程 Wasm 运行时。

不支持在 Web 浏览器中使用。

不支持本机文本渲染。

npm install --cpu=wasm32 sharp

FreeBSD

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

pkg install -y pkgconf vips

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

Linux 内存分配器

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

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

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

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

AWS Lambda

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

在与目标架构不同的机器上构建部署包时，请参阅跨平台部分，以帮助确定哪个包管理器合适以及如何配置它。

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

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

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

Bundler

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

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

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

Vite

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

import { defineConfig } from 'vite';

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

TypeScript

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

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

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

Fonts

创建文本图像或渲染包含文本元素的 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 and Windows

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

The specified procedure could not be found.