vite-plugin-cesium-change

v1.0.0

Published

3 months ago

Unofficial customized fork of vite-plugin-cesium

0High
0Medium
0Low

wanjunshijie

vite vite-plugin cesium cesiumjs

⚡ vite-plugin-cesium-change

一个用于在 Vite 项目中快速集成 Cesium 的插件。

本项目基于原项目 vite-plugin-cesium 修改，主要解决 Cesium 静态资源部署到 CDN、OSS、对象存储或其他第三方静态资源平台后，Workers、Assets、ThirdParty、Widgets 等资源路径无法正确加载的问题。

原项目许可证：MIT
本项目仓库：yelingkong/vite-plugin-cesium

特性

快速在 Vite 中配置 Cesium
自动处理 Cesium 运行时静态资源
支持开发环境和生产构建
支持 rebuildCesium 构建模式
支持将 Cesium 静态资源部署至 CDN、OSS、COS、S3、Nginx 静态站点等第三方平台
支持通过 cesiumBaseUrl 配置 CESIUM_BASE_URL
避免 Cesium 的 Worker、地形、影像、控件样式等资源因路径错误导致 404

安装

使用 npm：

npm i -D cesium vite vite-plugin-cesium-change

使用 pnpm：

pnpm add -D cesium vite vite-plugin-cesium-change

使用 yarn：

yarn add -D cesium vite vite-plugin-cesium-change

基础使用

在 vite.config.js 或 vite.config.ts 中配置插件：

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium()
  ]
});

在业务代码中使用 Cesium：

import * as Cesium from 'cesium';

const viewer = new Cesium.Viewer('cesiumContainer');

也可以按需导入：

import { Viewer } from 'cesium';

const viewer = new Viewer('cesiumContainer');

在项目入口文件中引入 Cesium 控件样式：

import 'cesium/Build/Cesium/Widgets/widgets.css';

CDN / OSS 部署

这是本插件修改版的核心功能。

Cesium 运行时不仅需要加载 JavaScript，还会额外请求以下静态资源目录：

Workers/
ThirdParty/
Assets/
Widgets/

当这些目录被上传到 CDN、阿里云 OSS、腾讯云 COS、AWS S3、MinIO、Nginx 等第三方静态资源平台时，必须将 Cesium 的资源基础路径配置为实际 CDN 地址。

使用 cesiumBaseUrl 配置资源根路径：

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium({
      cesiumBaseUrl: 'https://cdn.example.com/cesium'
    })
  ]
});

配置后，Cesium 会从以下地址请求运行时资源：

https://cdn.example.com/cesium/Workers/
https://cdn.example.com/cesium/ThirdParty/
https://cdn.example.com/cesium/Assets/
https://cdn.example.com/cesium/Widgets/

CDN 目录结构

上传静态资源时，请确保 CDN 上的目录结构与下面一致：

https://cdn.example.com/cesium/
├── Assets/
├── ThirdParty/
├── Widgets/
└── Workers/

通常将本地 Cesium 构建目录中的以下文件夹上传即可：

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

若插件配置会生成完整 Cesium 构建资源，也可上传构建输出目录内对应的 Cesium 静态资源文件夹。

CDN 示例

阿里云 OSS / CDN

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium({
      cesiumBaseUrl: 'https://static.example.com/cesium'
    })
  ]
});

腾讯云 COS / CDN

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium({
      cesiumBaseUrl: 'https://cdn.example.com/cesium/'
    })
  ]
});

自建 Nginx 静态资源服务

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium({
      cesiumBaseUrl: 'https://static.example.com/libs/cesium'
    })
  ]
});

cesiumBaseUrl 末尾是否包含 / 取决于插件内部的路径拼接逻辑。建议统一使用不带末尾 / 的写法，例如：https://cdn.example.com/cesium。

本地部署路径

如果不使用 CDN，默认由插件在构建时处理 Cesium 的静态资源。

例如项目部署在：

https://example.com/

Cesium 资源最终可访问路径通常类似：

https://example.com/cesium/Workers/
https://example.com/cesium/Assets/
https://example.com/cesium/Widgets/
https://example.com/cesium/ThirdParty/

如果你的项目部署在二级目录，例如：

https://example.com/project/

建议同时在 Vite 中配置 base：

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  base: '/project/',

  plugins: [
    cesium({
      cesiumBaseUrl: '/project/cesium'
    })
  ]
});

Options

`rebuildCesium`

类型： boolean
默认值： false

默认情况下，插件会复制最小必要 Cesium 文件到构建目录。

设置为 true 时，插件会从 Cesium 源码重新构建资源。

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium({
      rebuildCesium: true
    })
  ]
});

`cesiumBaseUrl`

类型： string
默认值： 插件默认生成的本地 Cesium 资源路径
用途： 指定 Cesium 运行时静态资源根目录

适用于：

CDN
阿里云 OSS
腾讯云 COS
AWS S3
MinIO
Nginx 静态资源服务器
独立静态资源域名
微前端或二级目录部署

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium({
      cesiumBaseUrl: 'https://cdn.example.com/libs/cesium'
    })
  ]
});

设置后，Cesium 的资源请求会基于该路径生成：

https://cdn.example.com/libs/cesium/Workers/
https://cdn.example.com/libs/cesium/Assets/
https://cdn.example.com/libs/cesium/ThirdParty/
https://cdn.example.com/libs/cesium/Widgets/

完整配置示例

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    vue(),

    cesium({
      rebuildCesium: false,

      // Cesium 静态资源托管在 CDN 时启用
      cesiumBaseUrl: 'https://cdn.example.com/cesium'
    })
  ]
});

示例代码

`src/main.js`

import { createApp } from 'vue';
import App from './App.vue';
import 'cesium/Build/Cesium/Widgets/widgets.css';

createApp(App).mount('#app');

`src/App.vue`

<template>
  <div id="cesiumContainer"></div>
</template>

<script setup>
import { onMounted } from 'vue';
import * as Cesium from 'cesium';

onMounted(() => {
  new Cesium.Viewer('cesiumContainer', {
    animation: false,
    timeline: false
  });
});
</script>

<style>
html,
body,
#app,
#cesiumContainer {
  width: 100%;
  height: 100%;
  margin: 0;
  overflow: hidden;
}
</style>

`index.html`

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Cesium + Vite</title>
  </head>

  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

常见问题

Worker 加载失败

如果控制台出现以下类型报错：

Failed to load module script
Failed to load resource: 404
Unable to load Cesium Worker

请检查：

cesiumBaseUrl 是否配置为正确的 CDN 或静态资源路径
CDN 中是否存在 Workers 目录
CDN 文件是否允许跨域访问
Workers 目录内的 .js 文件是否正确上传
CDN 是否错误地将 JavaScript 文件作为下载附件返回

控件无样式

请在入口文件中引入：

import 'cesium/Build/Cesium/Widgets/widgets.css';

并确认 CDN 中存在：

Widgets/

地形、影像或模型资源加载失败

确认 cesiumBaseUrl 所指向目录中完整存在：

Assets/
ThirdParty/
Workers/
Widgets/

Cesium 的基础资源路径与静态资源实际地址必须一致，否则 Cesium 在运行时会产生错误的资源请求路径。

开发与构建

在 package.json 中配置：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

启动开发环境：

npm run dev

构建生产包：

npm run build

预览生产构建：

npm run preview

迁移自 vite-plugin-cesium

原来的写法：

import cesium from 'vite-plugin-cesium';

替换为：

import cesium from 'vite-plugin-cesium-change';

基础场景下其余配置可以保持不变：

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-change';

export default defineConfig({
  plugins: [
    cesium()
  ]
});

若 Cesium 静态资源托管在 CDN，则增加：

cesium({
  cesiumBaseUrl: 'https://cdn.example.com/cesium'
})

License

MIT

本项目基于 nshen/vite-plugin-cesium 修改，并遵循原项目的 MIT License。