Sharp for JavaScript (Node.js): 完整指南及示例

简介：什么是 Sharp，为什么需要它？

\n\n

Sharp 是一个用 C++ 编写的高性能图像处理库，为 Node.js 提供了便捷的 API。它可以将 JPEG、PNG、WebP、AVIF、TIFF 和 GIF 格式的图像转换为其他格式，并支持调整大小、裁剪、旋转、添加特效等众多功能。

\n\n

Sharp 的主要优势在于速度。该库使用了原生的 libvips 库，使其比同类库（例如 Jimp 或 gm）快数倍。它非常适合用于：

\n

\n
• Web 服务器和 API — 动态处理头像、缩略图，上传前优化图像。
\n
• 批量处理 — 将数千张图像转换为所需格式和尺寸。
\n
• 创建缩略图和画廊 — 快速生成缩略图。
\n
• 优化图像体积 — 在无损（或可控有损）的情况下进行压缩。
\n

\n\n

Sharp 支持处理缓冲区、流（streams）和文件，使其能够灵活地集成到任何 Node.js 应用程序中。

\n\n

安装

\n\n

通过 npm 安装 Sharp。该库需要 Node.js 版本 12.13.0 或更高（建议使用 14+）。

\n\n

npm install sharp

\n\n

如果你使用 yarn：

\n\n

yarn add sharp

\n\n

重要提示：Sharp 在安装时会编译原生模块。如果遇到错误，请确保已安装 build-essential（Linux）或 Xcode Command Line Tools（macOS）。对于 Windows，通常需要 Visual Studio Build Tools。

\n\n

安装后，在你的项目中导入该库：

\n\n

const sharp = require('sharp');

\n\n

快速入门

\n\n

让我们编写一个简单的脚本，加载一张图像，将其宽度缩小到 300 像素（保持比例），并保存为 WebP 格式。

\n\n

const sharp = require('sharp');\nconst path = require('path');\n\nasync function quickStart() {\n    try {\n        await sharp('input.jpg')\n            .resize(300) // 宽度 300px，高度自动调整\n            .webp({ quality: 80 }) // 转换为 WebP，质量 80%\n            .toFile('output.webp');\n        \n        console.log('图像处理成功！');\n    } catch (error) {\n        console.error('错误：', error);\n    }\n}\n\nquickStart();

\n\n

这个示例展示了方法链（chaining），这是使用 Sharp 的基础。每个方法都返回一个新的 Sharp 实例，从而可以连续应用变换。

\n\n

主要方法和函数

\n\n

以下是 Sharp 的 10 个关键方法，包含详细描述、参数和代码示例。

\n\n

1. resize() — 调整图像大小

\n

功能：调整图像的宽度和/或高度。可以裁剪或使图像适应指定的边界框。

\n

参数：

\n

\n
• width (number, 可选) — 新的宽度（像素）。
\n
• height (number, 可选) — 新的高度（像素）。
\n
• options (object, 可选)：\n
  \n
  • fit (string) — 适应模式：'cover'（填充并裁剪多余部分）、'contain'（完整显示）、'fill'（拉伸）、'inside'（缩小以适应）、'outside'（放大以超出边界）。默认值为 'cover'。
  \n
  • position (string) — 裁剪时的位置：'center'、'top'、'left'、'right'、'bottom' 等。
  \n
  • withoutEnlargement (boolean) — 禁止放大图像。
  \n
  \n
\n

\n

示例：

\n

// 缩小到 200x200，从中心裁剪\nawait sharp