Внешние медиа‑ссылки (preview/runtime/export)

Этот гайд описывает, как платформа обрабатывает внешние ссылки на изображения/видео, и как выбрать режим для стабильной работы в preview, runtime‑host и export.

Режимы работы

Режим	Что происходит	Когда использовать
direct	Используется оригинальная ссылка без изменений	Если ссылки уже прямые и стабильные
normalized	Share‑ссылки приводятся к прямым URL	Стандартный режим по умолчанию
proxy	Нормализованный URL проксируется через backend	Если у источника нет CORS/redirect‑проблем

Поддерживаемые сервисы нормализации

Сервис	Пример входной ссылки	Что получает runtime
Google Drive	https://drive.google.com/file/d/<id>/view	https://drive.google.com/uc?export=download&id=<id>
Yandex Disk	https://yadi.sk/d/<key> или https://disk.yandex.ru/d/<key>	https://cloud-api.yandex.net/v1/disk/public/resources/download?public_key=<url>
Dropbox	https://www.dropbox.com/s/<id>/file.png?dl=0	https://www.dropbox.com/s/<id>/file.png?raw=1

Примечание: если ссылка не распознаётся, она остаётся как есть.

Где настраивается режим

Builder‑web

В Settings → External media → Media link mode можно выбрать режим для preview и для передачи в runtime‑host / export.

Runtime‑host

Режим можно передать через query‑параметр:

?mediaMode=direct|normalized|proxy

Export

Режим записывается в .env.example фронтенда:

VITE_MEDIA_MODE=normalized
VITE_MEDIA_PROXY_URL=http://localhost:3001

Media proxy

Если выбран режим proxy, runtime‑host или экспортируемый фронтенд будут обращаться к /media/proxy?url=... на backend.

Runtime‑backend env

MEDIA_PROXY_ENABLED=true
MEDIA_PROXY_ALLOWLIST=drive.google.com,docs.google.com,yadi.sk,disk.yandex.ru,dropbox.com,*.googleusercontent.com
MEDIA_PROXY_TIMEOUT_MS=10000
MEDIA_PROXY_MAX_BYTES=10485760

Backend шаблон (export)

Использует те же переменные окружения.

Ограничения

• В proxy режиме применяется allowlist доменов.
• Ответ ограничен по размеру (MEDIA_PROXY_MAX_BYTES).
• Для нестабильных share‑ссылок рекомендуется normalized или proxy.