Конфигурация активов

Обзор параметров конфигурации для Nette Assets.

assets:
	# base path for resolving relative mapper paths
	basePath: ...            # (string) defaults to %wwwDir%

	# base URL for resolving relative mapper URLs
	baseUrl: ...             # (string) defaults to %baseUrl%

	# enable asset versioning globally?
	versioning: ...           # (bool) defaults to true

	# defines asset mappers
	mapping: ...             # (array) defaults to path 'assets'

basePath устанавливает базовый каталог файловой системы для разрешения относительных путей в сопоставителях. По умолчанию используется веб-каталог (%wwwDir%).

baseUrl устанавливает базовый префикс URL для разрешения относительных URL в сопоставителях. По умолчанию используется корневой URL (%baseUrl%).

Опция versioning глобально управляет тем, добавляются ли параметры версии к URL активов для обхода кэша. Отдельные сопоставители могут переопределить этот параметр.

Сопоставители

Сопоставители могут быть настроены тремя способами: простая строковая нотация, подробная нотация массива или ссылка на сервис.

Самый простой способ определить сопоставитель:

assets:
	mapping:
		default: assets     # Creates filesystem mapper for %wwwDir%/assets/
		images: img         # Creates filesystem mapper for %wwwDir%/img/
		scripts: js         # Creates filesystem mapper for %wwwDir%/js/

Каждый сопоставитель создает FilesystemMapper, который:

• Ищет файлы в %wwwDir%/<path>
• Генерирует URL, такие как %baseUrl%/<path>
• Наследует глобальные настройки версионирования

Для большего контроля используйте подробную нотацию:

assets:
	mapping:
		images:
			# directory where files are stored
			path: ...                    # (string) optional, defaults to ''

			# URL prefix for generated links
			url: ...                     # (string) optional, defaults to path

			# enable versioning for this mapper?
			versioning: ...              # (bool) optional, inherits global setting

			# auto-add extension(s) when searching for files
			extension: ...               # (string|array) optional, defaults to null

Понимание того, как разрешаются значения конфигурации:

Разрешение пути

Относительные пути разрешаются из basePath (или %wwwDir%, если basePath не установлен)

Абсолютные пути используются как есть

Разрешение URL

Относительные URL разрешаются из baseUrl (или %baseUrl%, если baseUrl не установлен)

Абсолютные URL (со схемой или //) используются как есть

Если url не указан, используется значение path

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

	mapping:
		# Relative path and URL
		images:
			path: img                    # Resolved to: /var/www/project/www/img
			url: images                  # Resolved to: https://example.com/assets/images

		# Absolute path and URL
		uploads:
			path: /var/shared/uploads    # Used as-is: /var/shared/uploads
			url: https://cdn.example.com # Used as-is: https://cdn.example.com

		# Only path specified
		styles:
			path: css                    # Path: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Пользовательские сопоставители

Для пользовательских сопоставителей укажите ссылку или определите сервис:

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

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

Сопоставитель Vite

Сопоставитель Vite требует только добавления type: vite. Ниже приведен полный список параметров конфигурации:

assets:
	mapping:
		default:
			# mapper type (required for Vite)
			type: vite                # (string) required, must be 'vite'

			# Vite build output directory
			path: ...                 # (string) optional, defaults to ''

			# URL prefix for built assets
			url: ...                  # (string) optional, defaults to path

			# location of Vite manifest file
			manifest: ...             # (string) optional, defaults to <path>/.vite/manifest.json

			# Vite dev server configuration
			devServer: ...            # (bool|string) optional, defaults to true

			# versioning for public directory files
			versioning: ...           # (bool) optional, inherits global setting

			# auto-extension for public directory files
			extension: ...            # (string|array) optional, defaults to null

Опция devServer управляет тем, как активы загружаются во время разработки:

• true (по умолчанию) – Автоматически определяет сервер разработки Vite на текущем хосте и порту. Если сервер разработки запущен и ваше приложение находится в режиме отладки, активы загружаются с него с поддержкой горячей замены модулей. Если сервер разработки не запущен, активы загружаются из скомпилированных файлов в публичном каталоге.
• false – Полностью отключает интеграцию с сервером разработки. Активы всегда загружаются из скомпилированных файлов.
• Пользовательский URL (например, https://localhost:5173) – Вручную укажите URL сервера разработки, включая протокол и порт. Полезно, когда сервер разработки работает на другом хосте или порту.

Опции versioning и extension применяются только к файлам в публичном каталоге Vite, которые не обрабатываются Vite.

Ручная конфигурация

При неиспользовании Nette DI настройте сопоставители вручную:

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

$registry = new Registry;

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

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