Nainstalujte - dokumentaci sharp

Pracuje se správcem balíčků JavaScript podle vašeho výběru.

⚠️ Ujistěte se, že váš správce balíčků je nakonfigurován pro instalaci volitelných závislostí

Pokud musí lockfile správce balíčků podporovat více platforem, podívejte se prosím do sekce pro více platforem, která vám pomůže rozhodnout, který správce balíčků je vhodný.

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 ...

Předpoklady

Runtime kompatibilní s Node-API v9, jako je Node.js ^18.17.0 nebo >=20.3.0.

Předpřipravené binární soubory

Zkompilované ostré a libvips binární soubory jsou k dispozici pro nejběžnější platformy:

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 s SSE4.2)
Windows x64
Windows x86

To poskytuje podporu pro obrazové formáty JPEG, PNG, WebP, AVIF (s omezením na 8bitovou hloubku), TIFF, GIF a SVG (vstup).

Víceplatformní

V době instalace správce balíčků automaticky vybere předem sestavené binární soubory pro aktuální platformu OS a architekturu CPU, pokud jsou k dispozici.

Někteří správci balíčků podporují více platforem a architektur ve stejném instalačním stromu a/nebo používají stejný soubor zámku.

Npm v10+

⚠️ Soubor npm package-lock.json může způsobit problémy s instalací kvůli chybě npm#4828

Omezená podpora prostřednictvím příznaků --os, --cpu a --libc.

Podpora macOS s procesory Intel x64 a ARM64:

npm install --cpu=x64 --os=darwin sharp
Npm install --cpu=arm64 --os=darwin sharp

Pokud je křížovým cílem Linux, musí být zadána standardní knihovna C.

Pro podporu glibc (např. Debian) a musl (např. Alpine) Linux s procesory Intel x64:

npm install --cpu=x64 --os=linux --libc=glibc sharp
Npm install --cpu=x64 --os=linux --libc=musl sharp

Yarn v3+

Použijte konfiguraci SupportArchitectures.

Pnpm v8+

Použijte konfiguraci SupportArchitectures.

Vlastní libvips

Chcete-li použít vlastní, globálně nainstalovanou verzi libvips místo poskytnutého binárního souboru, ujistěte se, že se jedná alespoň o verzi uvedenou v engine.libvips v souboru package.json a že ji lze najít pomocí pkg-config --modversion vips- cpp.

Pro pomoc s kompilací libvips a jejich závislostí se prosím podívejte na vytváření libvips ze zdrojového kódu .

Použití globálně nainstalovaného libvips není podporováno ve Windows a macOS při spuštění Node.js pod Rosetta.

Sestavte ze zdroje

Tento modul bude zkompilován ze zdroje, když jej npm nainstaluje, pokud:

Je detekován globálně nainstalovaný libvips, popř
Když je použit příznak npm install --build-from-source.

Logiku detekce globálně nainstalované knihovny libvips lze přeskočit nastavením proměnných prostředí SHARP_IGNORE_GLOBAL_LIBVIPS (nikdy se ji nepokoušejte použít) nebo SHARP_FORCE_GLOBAL_LIBVIPS (vždy ji zkuste použít, i když chybí nebo je zastaralá).

Stavba ze zdroje vyžaduje:

kompilátor C++11
Node-addon-apiVersion 7+
Node-gypVersion 9+ a jeho závislosti

Tyto závislosti jsou kontrolovány během instalace. Pokud nejsou nalezeny node-addon-api nebo node-gyp, zkuste je přidat pomocí:

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

Pro křížovou kompilaci použijte ke konfiguraci cílového prostředí příznaky --platform, --arch a --libc npm (nebo proměnné prostředí npm_config_platform, npm_config_arch a npm_config_libc).

WebAssembly

Experimentální podpora pro vícevláknové běhové prostředí Wasm prostřednictvím Workers.

Není podporováno pro použití ve webových prohlížečích.

Nativní vykreslování textu není podporováno.

npm install --cpu=wasm32 sharp

FreeBSD

Balíček vips musí být nainstalován před spuštěním instalace npm.

pkg install -y pkgconf vips

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

Linux Memory Allocator

Výchozí alokátor paměti na většině linuxových systémů založených na glibc (např. Debian, Red Hat) není vhodný pro dlouhotrvající vícevláknové procesy zahrnující mnoho malých alokací paměti.

Z tohoto důvodu ve výchozím nastavení ostrý omezí použití souběžnosti založené na vláknech, když je za běhu detekován alokátor glibc.

Aby se předešlo fragmentaci a zlepšil se výkon na těchto systémech, doporučuje se použití alternativního alokátoru paměti, jako je jemalloc.

Uživatelé linuxových systémů založených na musl (jako je Alpine) a jiných systémů nejsou ovlivněni.

AWS Lambda

Adresář node_modules balíčku pro nasazení musí obsahovat binární soubory pro platformy linux-x64 nebo linux-arm64 v závislosti na zvolené architektuře.

Při sestavování balíčku nasazení na počítači, který se liší od cílové architektury, si přečtěte část pro více platforem, která vám pomůže rozhodnout, který správce balíčků je vhodný a jak jej nakonfigurovat.

Někteří správci balíčků používají symbolické odkazy, ale AWS Lambda je v balících nasazení nepodporuje.

Chcete-li dosáhnout nejlepšího výkonu, vyberte největší dostupnou paměť. Funkce 1536 MB poskytuje ~12x více času CPU než funkce 128 MB.

Při integraci s AWS API Gateway se ujistěte, že je nakonfigurována s příslušnými binárními typy médií.

Bundler

Webpack

Zajistěte, aby bylo ostré vyloučeno ze sdružování prostřednictvím externí konfigurace.

externals: {
  'sharp': 'commonjs sharp'
}

Esbuild

Zajistěte, aby bylo ostré vyloučeno ze sdružování prostřednictvím externí konfigurace.

buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  platform: 'node',
  external: ['sharp'],
})

esbuild app.js --bundle --platform=node --external:sharp

V případě serverless-esbuild zajistěte instalaci binárních souborů pro konkrétní platformu prostřednictvím konfigurace serverless.yml.

custom:
  esbuild:
    external:
      - sharp
    packagerOptions:
      scripts:
        - npm install --os=linux --cpu=x64 sharp

Electron

Zajistěte, aby byl ostrý rozbalen z archivu ASAR pomocí možnosti asarUnpack.

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

Vite

Zajistěte, aby bylo ostré vyloučeno ze sdružování prostřednictvím konfigurace build.rollupOptions.

import { defineConfig } from 'vite';

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

TypeScript

Definice TypeScript jsou vydány jako součást ostrého balíčku počínaje v0.32.0.

Dříve byly dostupné prostřednictvím balíčku @types/sharp, který je nyní zastaralý.

Když používáte Typescript, ujistěte se, že devDependencies zahrnuje balíček @types/node.

Fonts

Při vytváření textových obrázků nebo vykreslování obrázků SVG obsahujících textové prvky se k nalezení relevantních písem používá fontconfig.

V systémech Windows a macOS jsou k dispozici všechna systémová písma.

Na systémech macOS používajících Homebrew možná budete muset nastavit proměnnou prostředí PANGOCAIRO_BACKEND na hodnotu fontconfig, abyste zajistili, že se použije pro zjišťování písem namísto Core Text.

V systémech Linux jsou k dispozici k použití písma, která obsahují příslušnou konfiguraci fontconfig při instalaci prostřednictvím správce balíčků.

Pokud konfigurace fontconfig není nalezena, dojde k následující chybě:

Fontconfig error: Cannot load default config file

V prostředích bez serveru, kde nemůžete ovládat balíčky písem, použijte proměnnou prostředí FONTCONFIG_PATH, která ukáže na vlastní umístění.

Vložená písma SVG nejsou podporována.

Známé konflikty

Canvas and Windows

Pokud používáte canvas a ostré moduly ve stejném procesu Windows, může dojít k následujícím chybám:

The specified procedure could not be found.