Assets Konfiguration

Übersicht der Konfigurationsoptionen für Nette Assets.

assets:
	# Basispfad zum Auflösen relativer Mapper-Pfade
	basePath: ...            # (string) Standardwert ist %wwwDir%

	# Basis-URL zum Auflösen relativer Mapper-URLs
	baseUrl: ...             # (string) Standardwert ist %baseUrl%

	# Asset-Versionierung global aktivieren?
	versioning: ...           # (bool) Standardwert ist true

	# definiert Asset-Mapper
	mapping: ...             # (array) Standardwert ist der Pfad 'assets'

Der basePath legt das Standard-Dateisystemverzeichnis zum Auflösen relativer Pfade in Mappern fest. Standardmäßig wird das Webverzeichnis (%wwwDir%) verwendet.

Der baseUrl legt das Standard-URL-Präfix zum Auflösen relativer URLs in Mappern fest. Standardmäßig wird die Root-URL (%baseUrl%) verwendet.

Die Option versioning steuert global, ob Versionsparameter zu Asset-URLs für Cache-Busting hinzugefügt werden. Einzelne Mapper können diese Einstellung überschreiben.

Mapper

Mapper können auf drei Arten konfiguriert werden: einfache String-Notation, detaillierte Array-Notation oder als Referenz auf einen Dienst.

Die einfachste Art, einen Mapper zu definieren:

assets:
	mapping:
		default: assets     # Erstellt einen Dateisystem-Mapper für %wwwDir%/assets/
		images: img         # Erstellt einen Dateisystem-Mapper für %wwwDir%/img/
		scripts: js         # Erstellt einen Dateisystem-Mapper für %wwwDir%/js/

Jeder Mapper erstellt einen FilesystemMapper, der:

• Sucht nach Dateien in %wwwDir%/<path>
• Generiert URLs wie %baseUrl%/<path>
• Erbt die globale Versionierungseinstellung

Für mehr Kontrolle verwenden Sie die detaillierte Notation:

assets:
	mapping:
		images:
			# Verzeichnis, in dem Dateien gespeichert sind
			path: ...                    # (string) optional, Standardwert ist ''

			# URL-Präfix für generierte Links
			url: ...                     # (string) optional, Standardwert ist path

			# Versionierung für diesen Mapper aktivieren?
			versioning: ...              # (bool) optional, erbt globale Einstellung

			# Erweiterung(en) beim Suchen nach Dateien automatisch hinzufügen
			extension: ...               # (string|array) optional, Standardwert ist null

Verständnis, wie Konfigurationswerte aufgelöst werden:

Pfadauflösung

Relative Pfade werden von basePath (oder %wwwDir%, wenn basePath nicht gesetzt ist) aufgelöst

Absolute Pfade werden unverändert verwendet

URL-Auflösung

Relative URLs werden von baseUrl (oder %baseUrl%, wenn baseUrl nicht gesetzt ist) aufgelöst

Absolute URLs (mit Schema oder //) werden unverändert verwendet

Wenn url nicht angegeben ist, wird der Wert von path verwendet

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

	mapping:
		# Relativer Pfad und URL
		images:
			path: img                    # Aufgelöst zu: /var/www/project/www/img
			url: images                  # Aufgelöst zu: https://example.com/assets/images

		# Absoluter Pfad und URL
		uploads:
			path: /var/shared/uploads    # Unverändert verwendet: /var/shared/uploads
			url: https://cdn.example.com # Unverändert verwendet: https://cdn.example.com

		# Nur Pfad angegeben
		styles:
			path: css                    # Pfad: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Benutzerdefinierte Mapper

Für benutzerdefinierte Mapper verweisen oder definieren Sie einen Dienst:

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

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

Vite Mapper

Der Vite-Mapper erfordert lediglich, dass Sie type: vite hinzufügen. Dies ist eine vollständige Liste der Konfigurationsoptionen:

assets:
	mapping:
		default:
			# Mapper-Typ (erforderlich für Vite)
			type: vite                # (string) erforderlich, muss 'vite' sein

			# Vite Build-Ausgabeverzeichnis
			path: ...                 # (string) optional, Standardwert ist ''

			# URL-Präfix für gebaute Assets
			url: ...                  # (string) optional, Standardwert ist path

			# Speicherort der Vite-Manifestdatei
			manifest: ...             # (string) optional, Standardwert ist <path>/.vite/manifest.json

			# Vite Dev-Server-Konfiguration
			devServer: ...            # (bool|string) optional, Standardwert ist true

			# Versionierung für Dateien im öffentlichen Verzeichnis
			versioning: ...           # (bool) optional, erbt globale Einstellung

			# Auto-Erweiterung für Dateien im öffentlichen Verzeichnis
			extension: ...            # (string|array) optional, Standardwert ist null

Die Option devServer steuert, wie Assets während der Entwicklung geladen werden:

• true (Standard) – Erkennt den Vite Dev-Server auf dem aktuellen Host und Port automatisch. Wenn der Dev-Server läuft und Ihre Anwendung im Debug-Modus ist, werden Assets von dort mit Hot Module Replacement-Unterstützung geladen. Wenn der Dev-Server nicht läuft, werden Assets aus den gebauten Dateien im öffentlichen Verzeichnis geladen.
• false – Deaktiviert die Dev-Server-Integration vollständig. Assets werden immer aus den gebauten Dateien geladen.
• Benutzerdefinierte URL (z.B. https://localhost:5173) – Geben Sie die Dev-Server-URL manuell an, einschließlich Protokoll und Port. Nützlich, wenn der Dev-Server auf einem anderen Host oder Port läuft.

Die Optionen versioning und extension gelten nur für Dateien im öffentlichen Verzeichnis von Vite, die nicht von Vite verarbeitet werden.

Manuelle Konfiguration

Wenn Sie Nette DI nicht verwenden, konfigurieren Sie Mapper manuell:

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

$registry = new Registry;

// Dateisystem-Mapper hinzufügen
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

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