zainstalować

Współpracuje z wybranym menedżerem pakietów JavaScript.

⚠️ Upewnij się, że menedżer pakietów jest skonfigurowany do instalowania opcjonalnych zależności

Jeśli plik blokujący menedżera pakietów musi obsługiwać wiele platform, zapoznaj się z sekcją dotyczącą wielu platform, aby zdecydować, który menedżer pakietów jest odpowiedni.

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

Warunki wstępne

• Środowisko wykonawcze zgodne z Node-API v9, takie jak Node.js ^18.17.0 lub >=20.3.0.

Gotowe pliki binarne

Skompilowane pliki binarne Sharp i libvips są dostępne dla najpopularniejszych platform:

• 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, procesor z SSE4.2)
• Windows x64
• Windows x86

Zapewnia to obsługę formatów obrazów JPEG, PNG, WebP, AVIF (ograniczona do 8-bitowej głębokości), TIFF, GIF i SVG (wejście).

Wieloplatformowy

W czasie instalacji menedżer pakietów automatycznie wybierze gotowe pliki binarne dla bieżącej platformy systemu operacyjnego i architektury procesora, jeśli są dostępne.

Niektóre menedżery pakietów obsługują wiele platform i architektur w tym samym drzewie instalacyjnym i/lub przy użyciu tego samego pliku blokady.

Npm v10+

⚠️ Plik npm package-lock.json może powodować problemy z instalacją z powodu błędu npm#4828

Ograniczona obsługa flag --os, --cpu i --libc.

Aby obsługiwać system macOS z procesorami Intel x64 i ARM64:

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

Jeśli celem krzyżowym jest Linux, należy określić standardową bibliotekę C.

Aby obsługiwać glibc (np. Debian) i musl (np. Alpine) Linux z procesorami Intel x64:

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

Yarn v3+

Użyj konfiguracji obsługiwanej architektury.

Pnpm v8+

Użyj konfiguracji obsługiwanej architektury.

Niestandardowe libvipy

Aby użyć niestandardowej, globalnie zainstalowanej wersji libvips zamiast dostarczonego pliku binarnego, upewnij się, że jest to co najmniej wersja wymieniona w Engines.libvips w pliku package.json i że można ją znaleźć za pomocą pkg-config --modversion vips- cpp.

Aby uzyskać pomoc dotyczącą kompilacji libvips i jej zależności, zobacz budowanie libvips ze źródeł .

Korzystanie z globalnie zainstalowanej biblioteki libvips nie jest obsługiwane w systemach Windows i macOS podczas uruchamiania Node.js w środowisku Rosetta.

Kompiluj ze źródła

Ten moduł zostanie skompilowany ze źródła, gdy npm go zainstaluje, jeśli:

• Wykryto globalnie zainstalowaną bibliotekę libvips lub
• Gdy używana jest flaga npm install --build-from-source.

Logikę wykrywania globalnie zainstalowanej biblioteki libvips można pominąć, ustawiając zmienne środowiskowe SHARP_IGNORE_GLOBAL_LIBVIPS (nigdy nie próbuj jej używać) lub SHARP_FORCE_GLOBAL_LIBVIPS (zawsze próbuj jej używać, nawet jeśli jej brakuje lub jest nieaktualna).

Kompilowanie ze źródła wymaga:

• Kompilator C++11
• Node-addon-apiVersion 7+
• Node-gypVersion 9+ i jego zależności

Zależności te są sprawdzane podczas instalacji. Jeśli nie znaleziono węzła-addon-api lub węzła-gyp, spróbuj dodać je za pomocą:

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

W przypadku kompilacji krzyżowej użyj flag --platform, --arch i --libc npm (lub zmiennych środowiskowych npm_config_platform, npm_config_arch i npm_config_libc), aby skonfigurować środowisko docelowe.

WebAssembly

Eksperymentalne wsparcie dla wielowątkowych środowisk wykonawczych Wasm poprzez Workers.

Nieobsługiwane do użytku w przeglądarkach internetowych.

Natywne renderowanie tekstu nie jest obsługiwane.

npm install --cpu=wasm32 sharp

FreeBSD

Pakiet vips musi zostać zainstalowany przed uruchomieniem npm install.

pkg install -y pkgconf vips

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

Alokator pamięci w systemie Linux

Domyślny alokator pamięci w większości systemów Linux opartych na glibc (np. Debian, Red Hat) nie jest odpowiedni dla długotrwałych procesów wielowątkowych obejmujących wiele małych alokacji pamięci.

Z tego powodu, Sharp domyślnie ogranicza użycie współbieżności opartej na wątkach, gdy w czasie wykonywania zostanie wykryty alokator glibc.

Aby uniknąć fragmentacji i poprawić wydajność tych systemów, zaleca się użycie alternatywnego alokatora pamięci, takiego jak jemalloc.

Nie dotyczy to użytkowników systemów Linux opartych na musl (takich jak Alpine) i systemów innych niż Linux.

AWS Lambda

Katalog node_modules pakietu wdrożeniowego musi zawierać pliki binarne dla platformy linux-x64 lub linux-arm64, w zależności od wybranej architektury.

Kompilując pakiet wdrożeniowy na komputerze różniącym się od architektury docelowej, zapoznaj się z sekcją dotyczącą wielu platform, aby zdecydować, który menedżer pakietów jest odpowiedni i jak go skonfigurować.

Niektórzy menedżerowie pakietów używają dowiązań symbolicznych, ale AWS Lambda nie obsługuje ich w pakietach wdrożeniowych.

Aby uzyskać najlepszą wydajność, wybierz największą dostępną pamięć. Funkcja 1536 MB zapewnia ~12 razy więcej czasu procesora niż funkcja 128 MB.

Podczas integracji z bramą API AWS upewnij się, że jest ona skonfigurowana z odpowiednimi typami mediów binarnych.

Pakieter

Webpack

Upewnij się, że Sharp jest wykluczony z łączenia poprzez konfigurację zewnętrzną.

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

Esbuild

Upewnij się, że Sharp jest wykluczony z wiązania poprzez konfigurację zewnętrzną.

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

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

W przypadku esbuildu bezserwerowego upewnij się, że pliki binarne specyficzne dla platformy są zainstalowane poprzez konfigurację serverless.yml.

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

Electron

Upewnij się, że Sharp został rozpakowany z archiwum ASAR, używając opcji asarUnpack.

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

Vite

Upewnij się, że Sharp jest wykluczony z pakietowania za pomocą konfiguracji build.rollupOptions.

import { defineConfig } from 'vite';

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

TypeScript

Definicje TypeScriptu są wydawane jako część pakietu Sharp, począwszy od wersji 0.32.0.

Wcześniej były one dostępne za pośrednictwem pakietu @types/sharp, który jest obecnie przestarzały.

Korzystając z TypeScript, upewnij się, że devDependency zawiera pakiet @types/node.

Fonts

Podczas tworzenia obrazów tekstowych lub renderowania obrazów SVG zawierających elementy tekstowe do wyszukiwania odpowiednich czcionek używana jest funkcja Fontconfig.

W systemach Windows i macOS dostępne są wszystkie czcionki systemowe.

W systemach macOS korzystających z Homebrew może być konieczne ustawienie zmiennej środowiskowej PANGOCAIRO_BACKEND na wartość czcionkiconfig, aby mieć pewność, że będzie ona używana do wykrywania czcionek zamiast tekstu podstawowego.

W systemach Linux dostępne są czcionki zawierające odpowiednią konfigurację Fontconfig po zainstalowaniu za pomocą menedżera pakietów.

Jeśli konfiguracja Fontconfig nie zostanie znaleziona, wystąpi następujący błąd:

Fontconfig error: Cannot load default config file

W środowiskach bezserwerowych, w których nie można kontrolować pakietów czcionek, użyj zmiennej środowiskowej FONTCONFIG_PATH, aby wskazać niestandardową lokalizację.

Osadzone czcionki SVG nie są obsługiwane.

Znane konflikty

Canvas and Windows

Jeśli używasz modułów canvas i Sharp w tym samym procesie Windows, mogą wystąpić następujące błędy:

The specified procedure could not be found.