安装

  1. npm install sharp

或者

  1. yarn add sharp

先决条件

  • Node.js >= 12.13.0

预建的二进制文件

提供了已编译好的 Sharp 和 libvips 二进制文件，可在最常见的平台上使用:

  • macOS x64 (>= 10.13)
  • macOS ARM64
  • Linux x64 (glibc >= 2.17, musl >= 1.1.24, CPU with SSE4.2)
  • Linux ARM64 (glibc >= 2.17, musl >= 1.1.24)
  • Windows x64
  • Windows x86

包含 libvips 及其最常用依赖项的〜7MB 原始代码在npm install 期间会通过HTTPS下载并存储在node_modules/sharp/vendor 中。

这提供了对JPEG，PNG，WebP，AVIF, TIFF，GIF和SVG（输入）图像格式的支持。

以下平台已预先构建了 libvips，但不够完善：

  • Linux ARMv7 (glibc >= 2.28)
  • Linux ARMv6 (glibc >= 2.28)
  • Windows ARM64

以下平台需要从源代码编译 libvips 和 sharp ：

  • Linux x86
  • Linux ARMv7 (glibc <= 2.27, musl)
  • Linux ARMv6 (glibc <= 2.27, musl)
  • Linux PowerPC
  • FreeBSD
  • OpenBSD

常见问题

用于的Node.js的体系结构和平台必须与运行npm install 时使用的Node.js的体系结构和平台相同。如果不是这种情况，请参阅跨平台部分。

使用 npm v6 或更早版本时，以 root 或 sudo 用户身份安装时必须使用 npm install --unsafe-perm 标志。

使用 npm v7 或更高版本时，运行 npm install 的用户必须拥有运行它的目录。

npm 配置为忽略安装脚本时，必须使用 npm install --ignore-scripts=false 标志.

检查运行的输出以npm install --verbose sharp获取有用的错误消息。

Apple M1

从Sharp v0.29.0 版本开始，就为ARM64上的MacOS提供了预构建的Sharp和libvips二进制文件。

跨平台

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

可以使用以下标志手动选择目标平台或架构。

  1. npm install --platform=... --arch=... --arm-version=... sharp
  • --platform: 可选参数 linux, linuxmusl, darwin or win32.
  • --arch: 可选参数 x64, ia32, arm or arm64.
  • --arm-version: 可选参数 6, 7 or 8 (arm 默认为 to 6, arm64 默认为 to 8).
  • --sharp-install-force: 跳过版本兼容性和子资源完整性检查。

这些值也可以分别通过环境变量 npm_config_platform, npm_config_arch, npm_config_arm_version 和 SHARP_INSTALL_FORCE 设置。

例如，如果目标机器具有 64 位 ARM CPU 并且正在运行 Alpine Linux，使用以下标志:

  1. npm install --arch=arm64 --platform=linuxmusl sharp

自定义 libvips

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

有关从源代码编译libvips的帮助，请参阅 https://libvips.github.io/libvips/install.html#building-libvips-from-a-source-tarball .

Windows不支持使用全局安装的libvips。

从源代码构建

该模块npm install将在以下情况下从源代码编译：

  • 检测到全局安装的libvips（将环境变量设置为跳过此操作SHARP_IGNORE_GLOBAL_LIBVIPS），
  • 当前平台和Node.js版本不存在预构建的二进制文件
  • 使用该npm install --build-from-source标志时。

从源代码构建需要：

  • C++11 编译器
  • node-gyp 及其依赖项

定制的预建二进制文件

这是大多数人不需要的高级方法。

要从自定义URL安装预构建的Sharp二进制文件，请设置 npm 配置的 sharp_binary_host选项 或 npm_config_sharp_binary_host 环境变量.

要从本地文件系统上的目录安装预构建的 sharp 二进制文件，请设置 npm 配置的 sharp_local_prebuilds选项 或 npm_config_sharp_local_prebuilds 环境变量

要从自定义URL安装预构建的libvips二进制文件，请设置npm 配置的 sharp_libvips_binary_host选项或npm_config_sharp_libvips_binary_host环境变量。

版本子路径和文件名将附加到这些文件。例如，如果 sharp_libvips_binary_host 设置为 https://hostname/path 并且 libvips 版本为 1.2.3，则生成的 URL 将为 https://hostname/path/v1.2.3/libvips-1.2.3-platform-arch.tar.br

进一步的示例，请参见下面的中文镜像。

中国镜像

阿里巴巴在中国提供了一个镜像站点, 其中包含sharpjs和libvips的二进制文件。

要使用此功能，请设置以下配置：

  1. npm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
  2. npm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"
  3. npm install sharp

或设置以下环境变量：

  1. npm_config_sharp_binary_host="https://npmmirror.com/mirrors/sharp" \
  2.   npm_config_sharp_libvips_binary_host="https://npmmirror.com/mirrors/sharp-libvips" \
  3.   npm install sharp

FreeBSD

npm install前必须安装vips 。

  1. pkg install -y pkgconf vips
  1. cd /usr/ports/graphics/vips/ && make install clean

Linux memory allocator

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

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

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

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

Heroku

添加 jemalloc buildpack 以减少内存碎片的影响。

使用软件包管理器yarn时，将NODE_MODULES_CACHE 设置 为false 。

AWS Lambda

部署软件包的 node_modules 目录必须包含 Linux x64 平台的二进制文件

在 Linux x64 (glibc) 以外的机器上构建部署包时，请在 npm install 之后运行以下附加命令：

  1. npm install
  2. SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --arch=x64 --platform=linux sharp

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

打包器

webpack

使用外部配置externals将Sharp 排除在打包的之外。

  1. externals: {
  2.   'sharp': 'commonjs sharp'
  3. }

esbuild

使用外部配置externals将Sharp 排除在打包的之外。

  1. buildSync({
  2.   entryPoints: ['app.js'],
  3.   bundle: true,
  4.   platform: 'node',
  5.   external: ['sharp'],
  6. })
  1. esbuild app.js --bundle --platform=node --external:sharp

工作线程

主线程必须require('sharp') 在创建工作线程之前调用，以确保共享库在所有线程完成之前一直保持加载在内存中。

已知冲突

Canvas and Windows

canvas 为 Windows 提供的预构建二进制文件依赖于未维护的 GTK 2，最后一次更新是在 2011 年。

这些与Sharp提供的现行版本、最新的二进制文件相冲突。

如果两个模块在同一个Windows进程中使用，会出现如下错误：

  1. The specified procedure could not be found.