Vite настройка

CesiumJS представляет собой комплексную библиотеку для рендеринга трёхмерной геопространственной сцены в браузере. При использовании вместе с современными сборщиками модулей требуется учитывать особенности загрузки ассетов, Web Workers, WASM-модулей и статических ресурсов.

Vite обеспечивает быстрый dev-сервер, ESM-сборку и оптимизированный production-бандл, однако Cesium требует дополнительной настройки из-за своей нестандартной структуры пакета.

Особенности архитектуры Cesium в контексте Vite

Cesium отличается от типичных npm-библиотек:

  • наличие Web Workers (рендеринг, геометрия, текстуры)
  • использование статических ресурсов (Assets, Widgets, ThirdParty)
  • динамическая загрузка файлов через runtime URL
  • необходимость корректного base path
  • поддержка WebAssembly модулей

Vite по умолчанию обрабатывает зависимости как ESM, но Cesium содержит смешанный формат модулей и файловую структуру, требующую ручной конфигурации.

Инициализация проекта

Базовая структура проекта формируется через стандартный шаблон Vite:

npm create vite@latest cesium-vite-app
cd cesium-vite-app
npm install

Установка Cesium:

npm install cesium

Дополнительно часто требуется plugin для копирования статических ресурсов:

npm install vite-plugin-static-copy --save-dev

Базовая структура директорий Cesium

После установки Cesium важны следующие пути:

  • cesium/Build/Cesium/Workers
  • cesium/Build/Cesium/Assets
  • cesium/Build/Cesium/ThirdParty
  • cesium/Build/Cesium/Widgets

Эти директории не бандлятся автоматически Vite и должны быть скопированы в dist.

Конфигурация Vite для Cesium

Основной файл настройки vite.config.js требует определения алиасов и копирования статических ресурсов.

Алиасы и define

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      cesium: path.resolve(__dirname, 'node_modules/cesium/Source'),
    }
  },
  define: {
    CESIUM_BASE_URL: JSON.stringify('/cesium/')
  }
});

Копирование статических ресурсов

Cesium не может работать без корректной раздачи папки Build/Cesium.

Использование vite-plugin-static-copy:

import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/cesium/Build/Cesium/**/*',
          dest: 'cesium'
        }
      ]
    })
  ]
});

Результат сборки:

dist/
 ├── cesium/
 │   ├── Assets/
 │   ├── Workers/
 │   ├── ThirdParty/
 │   ├── Widgets/

Инициализация Cesium в приложении

Входной файл main.js:

import * as Cesium from 'cesium';
import 'cesium/Build/Cesium/Widgets/widgets.css';

const viewer = new Cesium.Viewer('app', {
  terrainProvider: Cesium.createWorldTerrain()
});

HTML:

<div id="app"></div>

Настройка base URL для ресурсов

Cesium требует корректного пути к статике:

window.CESIUM_BASE_URL = '/cesium/';

или через define в Vite:

define: {
  CESIUM_BASE_URL: JSON.stringify('/cesium/')
}

Ошибки неправильного base URL проявляются как:

  • отсутствие иконок
  • 404 на Workers
  • не загружаются terrain tiles

Работа с Web Workers в Vite

Cesium использует Web Workers для:

  • декодирования текстур
  • обработки геометрии
  • работы с terrain

Vite должен корректно резолвить worker-файлы. При необходимости применяется настройка:

export default defineConfig({
  worker: {
    format: 'es'
  }
});

Оптимизация сборки Cesium

Cesium — тяжёлая библиотека, поэтому важна оптимизация:

Динамический импорт

const Cesium = await import('cesium');

Исключение лишних модулей

export default defineConfig({
  build: {
    rollupOptions: {
      external: []
    }
  }
});

Настройка производственного окружения

В production важно учитывать:

  • корректный public path
  • CDN для Cesium assets
  • кеширование статических ресурсов

Пример конфигурации:

export default defineConfig({
  base: '/',
  build: {
    assetsDir: 'assets'
  }
});

Подключение terrain и imagery providers

Cesium часто используется с внешними провайдерами данных:

const viewer = new Cesium.Viewer('app', {
  imageryProvider: new Cesium.OpenStreetMapImageryProvider({
    url: 'https://a.tile.openstreetmap.org/'
  }),
  terrainProvider: Cesium.createWorldTerrain()
});

Использование переменных окружения

Vite поддерживает .env файлы:

VITE_CESIUM_TOKEN=your_token_here

Использование:

Cesium.Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_TOKEN;

Частые ошибки интеграции

1. Не загружаются Workers

Причина — отсутствует папка /cesium/Workers.

2. Пустая сцена

Причина — неправильный CESIUM_BASE_URL.

3. Ошибки MIME type

Причина — сервер не раздаёт .wasm как application/wasm.

Подключение WASM в Cesium

Cesium использует WebAssembly для ускорения вычислений:

Vite автоматически обрабатывает .wasm, но иногда требуется явная настройка:

export default defineConfig({
  assetsInclude: ['**/*.wasm']
});

Структура интеграции в реальном проекте

Типичная архитектура:

src/
 ├── cesium/
 │   ├── viewer.js
 │   ├── layers.js
 ├── main.js
public/
 ├── cesium/   (копируемый билд)
vite.config.js

Разделение логики Viewer

Инициализация Viewer выделяется в отдельный модуль:

export function createViewer(containerId) {
  return new Cesium.Viewer(containerId, {
    animation: false,
    timeline: false,
    geocoder: false
  });
}

Управление производительностью сцены

Оптимизационные параметры:

const viewer = new Cesium.Viewer('app', {
  requestRenderMode: true,
  maximumRenderTimeChange: Infinity
});

Работа с большим количеством сущностей

При массовой отрисовке объектов:

  • использовать EntityCollection
  • отключать лишние интерфейсные элементы
  • использовать batching геометрий
const points = viewer.entities;

for (let i = 0; i < 10000; i++) {
  points.add({
    position: Cesium.Cartesian3.fromDegrees(10 + i * 0.001, 50),
    point: { pixelSize: 3 }
  });
}
Оглавление