vite-plugin-mars3d使用说明

安装

//安装mars3d主库
npm install mars3d mars3d-cesium @turf/turf --save

//安装vite插件
npm install vite-plugin-mars3d --save

配置

vite.config.ts中引入plugin插件

import { defineConfig } from 'vite';
import { mars3dPlugin } from 'vite-plugin-mars3d';

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

如果你个性化需求，也可以按需传入参数

import { defineConfig } from 'vite';
import { mars3dPlugin } from 'vite-plugin-mars3d';

export default defineConfig({
  plugins: [
      mars3dPlugin({
        mars3dPackageName: "mars3d",
        mars3dRunPath: "assets/mars3d",//mars3d静态资源目录名称，仅 useStatic:true 时有效
        cesiumPackageName: "mars3d-cesium",
        cesiumRunPath: "assets/mars3d-cesium",//cesium静态资源目录名称
        useStatic: false,
        useExternal: false,
        injectCss: true,//是否自动在html中注入widgets.css/mars3d.css，自行控制样式引入时传false
        chunkSizeWarningLimit: 12000,//构建时chunk体积告警阈值(kB)，默认12000；恢复Vite默认告警传500
        mars3dPluginsPackageName: [],//mars3d插件包名，如 ['mars3d-space','mars3d-heatmap']，在 useStatic 和 useExternal 时生效
      }),
  ]
});

使用CDN或静态资源时

import { defineConfig } from 'vite';
import { mars3dPlugin } from 'vite-plugin-mars3d';

export default defineConfig({
  plugins: [
      mars3dPlugin({
        useExternal: true, //排除了引入包，html中手动静态引入相关资源 
      }),
  ]
});

环境要求与兼容性

• Node.js >= 20.19（Vite 7/8 要求；仅用 Vite 6 时 Node 18 亦可）
• Vite ^6.0.0 || ^7.0.0 || ^8.0.0（已在 Vite 6/7/8 下完成构建验证，不再支持 Vite 5）
• vite-plugin-static-copy ^4.1.1（作为依赖自动安装；请勿手动替换为 2.x 旧版，旧版 dev 中间件无法匹配 stripBase 拷贝目标，静态资源会被 SPA fallback 拦截返回 HTML）

注意事项

• useStatic 与 useExternal 互斥，不能同时为 true；同时传入时按 useExternal 处理并输出告警。
• Vite 8 下使用默认的非静态模式即可：rolldown 优化器首次预构建 mars3d（含其内部依赖的 cesium 巨包）耗时较长，dev 冷启动会慢一些，命中缓存后恢复正常；也可改用 useStatic: true，让 mars3d 全家桶走静态 script 外链以跳过预构建。
• 非静态模式下，插件会自动把 mars3d 及其插件包（mars3dPluginsPackageName）的真实路径加入 build.commonjsOptions.include，保证 UMD 产物按 CommonJS 处理，避免 Vite 6/7 生产构建后 mars3d.xxx 变为 undefined；file: 软链会按真实路径匹配，用户已有的 include 配置会被保留。Vite 8 由 rolldown 按模块语法原生识别 CJS，无需此项配置。

使用原生cesium时

1. 不要安装mars3d-cesium包，仅安装cesium包，就是不能同时存在2个cesium包 package.json文件示例:

  "dependencies": {
    "cesium": "^1.118.0",
    "mars3d": "^3.7.20",
    "mars3d-space": "^3.7.20",
    "rollup": "^2.79.1",
    "vue": "^3.2.47"
  },
  "devDependencies": {
    "vite": "^4.2.0",
    "vite-plugin-mars3d": "^4.1.0",
    "@vitejs/plugin-vue": "^4.1.0",
    "typescript": "^4.9.3",
    "vue-tsc": "^1.2.0"
  }

2. vite.config中引入时使用配置 mars3dPlugin({ cesiumPackageName: "cesium" })

vite.config.ts文件示例:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { mars3dPlugin } from "vite-plugin-mars3d"; // 引入插件


export default defineConfig({
  plugins: [
    vue(),
    mars3dPlugin({ cesiumPackageName: "cesium" }), // 使用cesium原生包
  ],
});

参考

https://github.com/nshen/vite-plugin-cesium

常见问题

• 如果项目的 package.json 没有 type:"module" ，请使用 "vite-plugin-mars3d":"~3.1.3"
• 如果项目的 package.json 有 type:"module" 直接用最新版本即可。
• 如果无法排除解决问题，也可以在vite.config.ts配置改为静态引入 mars3dPlugin({ useStatic: true })

本地开发与联调

npm run build    # tsc 类型检查 + vite 构建，产物输出到 dist
npm run copy     # 仅把 dist 拷贝到关联示例工程的 node_modules（不重新构建）

npm run copy 会把 dist/ 同步到以下示例工程的 node_modules/vite-plugin-mars3d/dist/，便于直接联调：

• mars3d-vue-project/
• mars3d-vue-app/
• mars3d-vue-project-mlxc/

注意：示例工程以 node_modules 依赖方式引入插件，Vite 会预构建并缓存依赖。重新 copy 后需要重启示例的 dev 服务（或使用 vite --force）才能加载到最新产物。

Mars3D 是什么

Mars3D平台 是火星科技研发的一款基于 WebGL 技术实现的三维客户端开发平台，基于Cesium优化提升与 B/S 架构设计，支持多行业扩展的轻量级高效能 GIS 开发平台，能够免安装、无插件地在浏览器中高效运行，并可快速接入与使用多种 GIS 数据和三维模型，呈现三维空间的可视化，完成平台在不同行业的灵活应用。

Mars3D 平台可用于构建无插件、跨操作系统、 跨浏览器的三维 GIS 应用程序。平台使用 WebGL 来进行硬件加速图形化，跨平台、跨浏览器来实现真正的动态大数据三维可视化。通过 Mars3D 产品可快速实现浏览器和移动端上美观、流畅的三维地图呈现与空间分析。

相关网站

• Mars3D 官网：http://mars3d.cn

• Mars3D 开源项目列表：https://github.com/marsgis/mars3d

版权说明

1. Mars3D 平台由火星科技自主研发，拥有所有权利。
2. 任何个人或组织可以在遵守相关要求下可以免费无限制使用。