Production сборка

Production-сборка в CesiumJS требует учета особенностей архитектуры движка: работа с Web Workers, загрузка статических ассетов (Assets), шейдеров, текстур и бинарных данных, а также корректная интеграция с модульной системой сборщика (Vite, Webpack, Rollup).

Ключевая особенность CesiumJS заключается в том, что это не просто JavaScript-библиотека, а полноценный WebGL-движок, зависящий от внешних ресурсов, которые должны быть доступны в итоговой сборке без нарушения структуры директорий.

Архитектура CesiumJS в контексте сборки

CesiumJS состоит из нескольких критически важных компонентов:

  • ядро JavaScript API;
  • Web Workers (рендеринг и геометрические вычисления);
  • статические ресурсы (Shaders, Textures, Widgets, Third-party);
  • Cesium Widgets (UI-компоненты);
  • системы загрузки тайлов и 3D Tiles.

При production-сборке необходимо обеспечить:

  • корректное копирование Assets;
  • правильное разрешение путей к Workers;
  • минимизацию и tree-shaking без повреждения динамических импортов;
  • сохранение структуры папок Build/Cesium.

Установка и базовая интеграция

CesiumJS обычно устанавливается через npm:

npm install cesium

После установки структура пакета включает:

  • Build/Cesium/ — готовые собранные файлы;
  • Source/ — исходники (используются при кастомной сборке);
  • Workers/ — вычислительные модули;
  • Assets/ — шрифты, изображения, иконки;
  • Widgets/ — UI компоненты.

Настройка переменных окружения

CesiumJS требует определения базового пути к статическим ресурсам:

import * as Cesium from "cesium";

window.CESIUM_BASE_URL = "/cesium/";

Этот путь должен указывать на директорию, куда будут скопированы:

  • Assets
  • Widgets
  • Workers
  • ThirdParty

Без корректного CESIUM_BASE_URL рендеринг сцен будет нарушен: не загрузятся текстуры, UI и шейдеры.

Production-сборка с Webpack

Webpack требует ручной настройки копирования ресурсов.

Установка зависимостей

npm install cesium copy-webpack-plugin webpack webpack-cli

Конфигурация

const path = require("path");
const CopyWebpackPlugin = require("copy-webpack-plugin");
const cesiumSource = "node_modules/cesium/Source";
const cesiumWorkers = "node_modules/cesium/Build/Cesium/Workers";

module.exports = {
  entry: "./src/index.js",
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist"),
  },
  resolve: {
    alias: {
      cesium: path.resolve(__dirname, cesiumSource),
    },
  },
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        { from: cesiumWorkers, to: "Workers" },
        { from: path.join(cesiumSource, "Assets"), to: "Assets" },
        { from: path.join(cesiumSource, "Widgets"), to: "Widgets" },
        { from: path.join(cesiumSource, "ThirdParty"), to: "ThirdParty" },
      ],
    }),
  ],
};

Production-сборка с Vite

Vite требует иной подход из-за ESM-модели и оптимизации зависимостей.

Установка

npm install cesium vite vite-plugin-static-copy

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

import { defineConfig } from "vite";
import cesium from "vite-plugin-cesium";

export default defineConfig({
  plugins: [cesium()],
  build: {
    sourcemap: false,
    minify: "esbuild",
  },
});

Плагин автоматически:

  • копирует Assets;
  • настраивает Workers;
  • корректирует пути загрузки ресурсов.

Работа с Web Workers

CesiumJS активно использует Web Workers для:

  • расчета геометрии;
  • декодирования terrain;
  • обработки 3D Tiles;
  • оптимизации рендера.

При сборке важно, чтобы Workers были доступны как отдельные файлы:

/dist/Workers/*.js

Ошибка в путях приводит к деградации производительности и fallback-режиму без многопоточности.

Минификация и tree-shaking

CesiumJS частично поддерживает tree-shaking, но с ограничениями:

  • динамические импорты мешают полной оптимизации;
  • часть модулей имеет side effects;
  • Workers и шейдеры не могут быть tree-shaken.

Рекомендации:

  • использовать mode: "production";
  • избегать глубоких импортов вида cesium/Source/*;
  • импортировать через основной entry:
import * as Cesium from "cesium";

Оптимизация размера бандла

CesiumJS — крупная библиотека, поэтому критична оптимизация:

1. Отключение ненужных компонентов

viewer.scene.globe.enableLighting = false;
viewer.scene.fog.enabled = false;

2. Использование CDN для Cesium

<script src="https://cesium.com/downloads/cesiumjs/releases/1.118/Build/Cesium/Cesium.js"></script>

В этом случае локальный бандл уменьшается, но теряется контроль над версией.

Статические ресурсы и их структура

Production-деплой требует строгого сохранения структуры:

/dist
  /Assets
  /Widgets
  /Workers
  /ThirdParty
  Cesium.js
  Cesium.css

Assets

  • изображения и UI-иконки;
  • шрифты;
  • модели и вспомогательные ресурсы.

Widgets

  • интерфейс Cesium Viewer;
  • кнопки навигации;
  • таймлайн и тулбары.

Workers

  • многопоточные вычисления.

Настройка публичного пути (public path)

В Webpack:

output: {
  publicPath: "/cesium-app/",
}

В Cesium:

window.CESIUM_BASE_URL = "/cesium-app/";

Несоответствие этих значений приводит к ошибкам загрузки ресурсов.

Source Maps в production

CesiumJS можно отлаживать в production через source maps:

module.exports = {
  devtool: "source-map",
};

Однако:

  • увеличивается размер сборки;
  • замедляется загрузка;
  • нежелательно для публичных релизов.

Кэширование и CDN-доставка

CesiumJS хорошо подходит для CDN-архитектуры:

  • статические Assets кэшируются агрессивно;
  • Workers можно версионировать;
  • Tileset данные загружаются лениво.

Рекомендуется:

  • использовать hash в именах файлов;
  • разделять релизы по версиям;
  • хранить 3D Tiles отдельно от приложения.

Интеграция с Cesium ion

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

Cesium.Ion.defaultAccessToken = "YOUR_TOKEN";

Токен должен быть доступен в runtime, но не попадать в публичный репозиторий.

Частые проблемы production-сборки

1. Белый экран при запуске

Причина:

  • неправильный CESIUM_BASE_URL;
  • отсутствуют Workers.

2. Ошибки загрузки шейдеров

Причина:

  • Assets не скопированы;
  • неправильные пути к ThirdParty.

3. Потеря производительности

Причина:

  • Workers не работают;
  • сборка разрушила модульную структуру;
  • отключен hardware acceleration.

4. Некорректный рендер тайлов

Причина:

  • CDN блокирует запросы;
  • неверная конфигурация CORS;
  • отсутствует HTTPS.

Структура production-пайплайна

Типичный pipeline включает:

  1. сборку JS-бандла;
  2. копирование Cesium Assets;
  3. оптимизацию статических ресурсов;
  4. генерацию хэшей файлов;
  5. деплой на CDN или static hosting;
  6. проверку загрузки Workers и Tiles.

Производительность в production-режиме

Критические факторы:

  • количество одновременно загружаемых tiles;
  • уровень детализации terrain;
  • использование request render mode;
  • batching геометрии.

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

  • frustum culling;
  • level-of-detail (LOD);
  • GPU instancing;
  • asynchronous tile loading.

Режимы сборки и окружения

CesiumJS различает несколько режимов:

  • development — расширенная диагностика;
  • production — минимизация и отключение debug;
  • sandbox — изолированное выполнение сцен.

В production отключаются:

  • debug overlay;
  • логирование WebGL ошибок;
  • часть проверок геометрии.

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

Обобщённая конфигурация включает:

  • корректный bundler (Webpack/Vite);
  • копирование Assets/Workers/Widgets;
  • настройку CESIUM_BASE_URL;
  • оптимизацию production mode;
  • поддержку CDN и кеширования;
  • контроль Web Workers.

Типовая схема развертывания

Browser
  ↓
CDN (Cesium build + Assets)
  ↓
Application bundle (Vite/Webpack)
  ↓
Workers (parallel execution)
  ↓
3D Tiles / Terrain servers

Архитектура ориентирована на минимизацию main thread и перенос вычислений в worker-слой, что делает production-сборку не просто процессом упаковки, а конфигурацией распределённой графической системы.

Оглавление