Какую систему адаптеров использует SvelteKit для деплоя и как выбрать нужный адаптер?

Что такое адаптеры SvelteKit

Адаптер — плагин сборки, который преобразует вывод vite build в формат, понятный конкретной платформе деплоя. SvelteKit производит платформо-нейтральный вывод; адаптер затем упаковывает его для Node.js, Cloudflare Workers, Vercel, Netlify или статического хостинга.

Встроенные адаптеры

• @sveltejs/adapter-auto — автоопределение платформы (Vercel, Netlify, Cloudflare). Рекомендуется при деплое на поддерживаемые платформы.
• @sveltejs/adapter-node — создаёт standalone Node.js-сервер. Используется для Docker, VPS, любого Node-хостинга.
• @sveltejs/adapter-static — полная предрендеровка в статические HTML/JS/CSS. Требует prerender = true на всех страницах или fallback для SPA.
• @sveltejs/adapter-cloudflare — для Cloudflare Pages + Workers (Edge Runtime, Web Crypto API).
• @sveltejs/adapter-vercel — для Vercel (Edge Functions или Serverless).
• @sveltejs/adapter-netlify — для Netlify Functions.

Настройка adapter-node

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      out: 'build',          // выходная директория
      precompress: true,     // gzip + brotli для статики
      envPrefix: 'MY_APP_', // PREFIX для env-переменных
    })
  }
};

После сборки запуск: node build/index.js. Порт задаётся через PORT env-переменную.

Настройка adapter-static (SPA-режим)

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: '200.html',  // SPA fallback для клиентского роутинга
      precompress: false,
    })
  }
};

Для SPA нужно отключить SSR глобально:

// src/routes/+layout.js
export const ssr = false;
export const prerender = false;

Настройка adapter-cloudflare

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

export default {
  kit: {
    adapter: adapter({
      routes: {
        include: ['/*'],
        exclude: ['<all>']
      }
    })
  }
};

Деплой: wrangler pages deploy build/. Привязки (KV, D1, R2) доступны через platform.env в серверных функциях.

Как выбрать адаптер

• Vercel/Netlify → adapter-auto или платформенный адаптер.
• Docker / VPS / Kubernetes → adapter-node.
• Документация / маркетинговый сайт без динамики → adapter-static.
• Edge (низкая латентность, глобальное распределение) → adapter-cloudflare.
• Ограниченный бюджет с serverless → adapter-vercel с Edge Functions.

Подводные камни

• adapter-auto в неизвестном окружении (например, Railway) падает при билде — нужно явно указать адаптер.
• adapter-static несовместим со страницами, использующими серверные функции (+server.ts, load с server-контекстом).
• Edge-адаптеры не поддерживают Node.js API (fs, crypto, Buffer) — нужны Web API аналоги (globalThis.crypto).
• При precompress: true в adapter-node сервер сам не отдаёт brotli — нужен nginx или обёртка, которая проверяет Accept-Encoding.
• Переменные окружения в adapter-static недоступны в runtime (только в build time через $env/static/public).
• Версии адаптеров должны совпадать с мажорной версией SvelteKit — смешение версий приводит к ошибкам типов.
• Cloudflare Workers имеют лимит на размер бандла (1 МБ для бесплатного плана) — тяжёлые зависимости могут не пройти.

• Путать SvelteKit adapters с похожим API из соседнего фреймворка.
• Не объяснять, где код выполняется: сервер, клиент, build step или runtime.
• Игнорировать влияние на hydration, cache, bundle size или безопасность.

• Точно объясняет назначение механизма «SvelteKit adapters».
• Показывает корректный минимальный пример без выдуманных API.
• Называет ограничения, failure modes и production-компромиссы.