Konfiguracja zasobów

Przegląd opcji konfiguracyjnych dla Nette Assets.

assets:
	# ścieżka bazowa do rozwiązywania względnych ścieżek mappera
	basePath: ...            # (string) domyślnie %wwwDir%

	# bazowy URL do rozwiązywania względnych URL mappera
	baseUrl: ...             # (string) domyślnie %baseUrl%

	# włączyć globalne wersjonowanie zasobów?
	versioning: ...           # (bool) domyślnie true

	# definiuje mappery zasobów
	mapping: ...             # (array) domyślnie ścieżka 'assets'

Opcja basePath ustawia domyślny katalog systemu plików do rozwiązywania ścieżek względnych w mapperach. Domyślnie używa katalogu webowego (%wwwDir%).

Opcja baseUrl ustawia domyślny prefiks URL do rozwiązywania względnych adresów URL w mapperach. Domyślnie używa głównego URL (%baseUrl%).

Opcja versioning globalnie kontroluje, czy parametry wersji są dodawane do adresów URL zasobów w celu unieważnienia pamięci podręcznej. Poszczególne mappery mogą nadpisać to ustawienie.

Mappery

Mappery można konfigurować na trzy sposoby: prostą notacją stringową, szczegółową notacją tablicową lub jako odwołanie do usługi.

Najprostszy sposób zdefiniowania mappera:

assets:
	mapping:
		default: assets     # Tworzy mapper systemu plików dla %wwwDir%/assets/
		images: img         # Tworzy mapper systemu plików dla %wwwDir%/img/
		scripts: js         # Tworzy mapper systemu plików dla %wwwDir%/js/

Każdy mapper tworzy FilesystemMapper, który:

• Szuka plików w %wwwDir%/<path>
• Generuje adresy URL takie jak %baseUrl%/<path>
• Dziedziczy globalne ustawienie wersjonowania

Dla większej kontroli użyj szczegółowej notacji:

assets:
	mapping:
		images:
			# katalog, w którym przechowywane są pliki
			path: ...                    # (string) opcjonalnie, domyślnie ''

			# prefiks URL dla generowanych linków
			url: ...                     # (string) opcjonalnie, domyślnie ścieżka

			# włączyć wersjonowanie dla tego mappera?
			versioning: ...              # (bool) opcjonalnie, dziedziczy ustawienie globalne

			# automatycznie dodawaj rozszerzenie(a) podczas wyszukiwania plików
			extension: ...               # (string|array) opcjonalnie, domyślnie null

Zrozumienie, jak rozwiązywane są wartości konfiguracyjne:

Rozwiązywanie ścieżek

Ścieżki względne są rozwiązywane z basePath (lub %wwwDir%, jeśli basePath nie jest ustawione)

Ścieżki bezwzględne są używane bez zmian

Rozwiązywanie URL

Względne adresy URL są rozwiązywane z baseUrl (lub %baseUrl%, jeśli baseUrl nie jest ustawione)

Bezwzględne adresy URL (ze schematem lub //) są używane bez zmian

Jeśli url nie jest określone, używa wartości path

assets:
	basePath: /var/www/project/www
	baseUrl: https://example.com/assets

	mapping:
		# Względna ścieżka i URL
		images:
			path: img                    # Rozwiązane do: /var/www/project/www/img
			url: images                  # Rozwiązane do: https://example.com/assets/images

		# Bezwzględna ścieżka i URL
		uploads:
			path: /var/shared/uploads    # Użyte bez zmian: /var/shared/uploads
			url: https://cdn.example.com # Użyte bez zmian: https://cdn.example.com

		# Określono tylko ścieżkę
		styles:
			path: css                    # Ścieżka: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Niestandardowe mappery

Dla niestandardowych mapperów, odwołaj się lub zdefiniuj usługę:

services:
	s3mapper: App\Assets\S3Mapper(%s3.bucket%)

assets:
	mapping:
		cloud: @s3mapper
		database: App\Assets\DatabaseMapper(@database.connection)

Vite Mapper

Mapper Vite wymaga jedynie dodania type: vite. Poniżej znajduje się pełna lista opcji konfiguracyjnych:

assets:
	mapping:
		default:
			# typ mappera (wymagany dla Vite)
			type: vite                # (string) wymagany, musi być 'vite'

			# katalog wyjściowy kompilacji Vite
			path: ...                 # (string) opcjonalnie, domyślnie ''

			# prefiks URL dla zbudowanych zasobów
			url: ...                  # (string) opcjonalnie, domyślnie ścieżka

			# lokalizacja pliku manifestu Vite
			manifest: ...             # (string) opcjonalnie, domyślnie <path>/.vite/manifest.json

			# konfiguracja serwera deweloperskiego Vite
			devServer: ...            # (bool|string) opcjonalnie, domyślnie true

			# wersjonowanie dla plików z katalogu publicznego
			versioning: ...           # (bool) opcjonalnie, dziedziczy ustawienie globalne

			# automatyczne rozszerzenie dla plików z katalogu publicznego
			extension: ...            # (string|array) opcjonalnie, domyślnie null

Opcja devServer kontroluje, jak zasoby są ładowane podczas developmentu:

• true (domyślnie) – Automatycznie wykrywa serwer deweloperski Vite na bieżącym hoście i porcie. Jeśli serwer deweloperski jest uruchomiony i Twoja aplikacja jest w trybie debugowania, zasoby są ładowane z niego z obsługą Hot Module Replacement. Jeśli serwer deweloperski nie jest uruchomiony, zasoby są ładowane ze zbudowanych plików w katalogu publicznym.
• false – Całkowicie wyłącza integrację z serwerem deweloperskim. Zasoby są zawsze ładowane ze zbudowanych plików.
• Niestandardowy URL (np. https://localhost:5173) – Ręcznie określ URL serwera deweloperskiego, włączając protokół i port. Przydatne, gdy serwer deweloperski działa na innym hoście lub porcie.

Opcje versioning i extension dotyczą tylko plików w katalogu publicznym Vite, które nie są przetwarzane przez Vite.

Konfiguracja ręczna

Gdy nie używasz Nette DI, skonfiguruj mappery ręcznie:

use Nette\Assets\Registry;
use Nette\Assets\FilesystemMapper;
use Nette\Assets\ViteMapper;

$registry = new Registry;

// Dodaj mapper systemu plików
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

// Dodaj mapper Vite
$registry->addMapper('app', new ViteMapper(
	baseUrl: '/build',
	basePath: __DIR__ . '/www/build',
	manifestPath: __DIR__ . '/www/build/.vite/manifest.json',
	devServer: 'https://localhost:5173',
));