必须安装sharp库，因其基于libvips，轻量高效、支持流式裁剪且无需系统依赖；原生Node API无法处理JPEG/PNG，其他库如gm或canvas存在维护或编译问题。
Node 脚本裁剪图片必须装什么库
直接用 Node 原生 API 无法读写 JPEG/PNG，必须依赖图像处理库。sharp 是目前最轻、最快、最稳的选择——它底层用 libvips，内存占用低，支持流式处理，批量裁剪时不会轻易 OOM。别选 gm（GraphicsMagick 绑定）或 canvas（需预装 Cairo），前者已多年不维护，后者编译失败率高，尤其在 Windows 或 M1 Mac 上。
安装命令：
npm install sharp
-
sharp不需要全局安装，也不依赖系统级图像工具（如 ImageMagick） - 若遇到
Cannot find module 'sharp'，确认node_modules下有该包，且当前工作目录是项目根目录 - M1/M2 Mac 用户如果报
cannot be loaded because its file type is not supported，运行npm rebuild sharp --platform=darwin --arch=arm64
用 sharp.resize() 和 sharp.extract() 的区别在哪
裁剪（crop）和缩放（resize）是两件事：resize() 改变整图宽高比或像素尺寸，适合等比压缩；extract() 才是真正“抠出指定区域”，不改变像素内容，只截取子矩形。批量处理中常混淆二者，导致输出图变形或偏移。
例如要从每张图左上角裁下 800×600 区域：
Rydberg Agent Node
下载
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
const sharp = require('sharp');
sharp(inputPath)
.extract({ left: 0, top: 0, width: 800, height: 600 })
.toFile(outputPath);
- 若用
resize({ width: 800, height: 600, fit: 'fill' })，会强行拉伸/压缩原图填满，不是裁剪 - 若原图尺寸小于目标裁剪区域（如想裁 800×600，但原图只有 600×400），
extract()会抛错Input buffer contains unsupported image format—— 实际是尺寸越界，需提前用metadata()检查 -
extract()的left/top支持小数，但最终按整像素截取；负值会被截断为 0
VSCode 里怎么跑脚本并看到错误堆栈
别在 VSCode 终端里手动敲 node crop.js 后反复修改再回车。直接配一个可调试的 launch 配置，出错时点一下就能跳转到源码行，还能设断点看 metadata() 返回的宽高。
在项目根目录建 .vscode/launch.json，内容如下：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Run crop script",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/crop.js",
"console": "integratedTerminal"
}
]
}
- 确保
crop.js文件存在，且第一行没加 BOM（Windows 记事本易产生，会导致Cannot use import statement outside a module） - 如果脚本用了
import语法，需在package.json中加"type": "module"，否则报错 - VSCode 调试时默认不显示
sharp的底层 C++ 错误，若卡住无输出，先在终端里跑一遍node crop.js看原始报错
批量处理时路径、并发和文件覆盖怎么防坑
常见崩溃点不在图像逻辑，而在文件系统操作：路径拼错、异步乱序、重复写同一文件、中文路径乱码。
- 用
path.join(__dirname, 'input', filename)拼路径，别用字符串拼接__dirname + '/input/' + filename（Windows 反斜杠会出问题） - 不要用
fs.readdirSync().forEach()直接调sharp().toFile()—— 这会并发开几十个写入流，容易触发 EMFILE 错误。改用Promise.allSettled()控制并发数，例如每次最多 5 个：
const files = await fs.promises.readdir(inputDir); const limit = pLimit(5); // 需 npm install p-limit await Promise.allSettled( files.map(f => limit(() => processOneFile(f))) );
- 输出路径务必保证唯一：
output/${path.parse(f).name}-crop.jpg，避免多张图输出到同名文件被覆盖 - Windows 用户若路径含中文，
sharp旧版本（sharp@^18.0.0 可解决
真正麻烦的是原图方向（EXIF orientation）——手机拍的照片常带旋转标记，sharp 默认不自动矫正。如果裁剪后发现图是横的，得加 .rotate() 或设 withMetadata({ orientation: true })。这个细节，90% 的批量脚本一开始都漏掉。
