1.npm包安装方式集成到项目

约 2282 字大约 8 分钟

2024-12-20

Mars3D 提供了多种获取 SDK 类库和集成的方式，你可以根据项目的实际情况和技术栈，从下面方式中任选一种安装。

1. npm包安装方式：适合 Vue、React 等基于 Node 的开发框架项目，推荐使用。
1. 静态引入方式 : 适合原生项目、npm安装存在问题时、离线内网环境、所有技术栈都可以使用。
1. CDN方式集成到项目 : 适合临时演示及快速开始使用，不适合生产环境(CDN存在不稳定的情况)。

1. 从 npm 安装获取SDK

使用 Node 环境下的现代 web 前端技术栈时，可以使用 npm 或 pnpm 或 yarn 等方式来安装 mars3d 包

npm

//安装mars3d主库，其中mars3d-cesium  @turf/turf为依赖库
npm install mars3d mars3d-cesium  @turf/turf  --save

//安装mars3d插件（按需安装）
npm install mars3d-space --save

pnpm

//安装mars3d主库，其中mars3d-cesium  @turf/turf为依赖库
pnpm add mars3d mars3d-cesium  @turf/turf

//安装mars3d插件（按需安装）
pnpm add mars3d-space --save

yarn

//安装mars3d主库，其中mars3d-cesium  @turf/turf为依赖库
yarn add mars3d mars3d-cesium  @turf/turf

//安装mars3d插件（按需安装）
yarn add mars3d-space --save

3. 增加DIV展示容器

在需要呈现Mars3D地图的html页面或相关vue/react等组件中，加上 div 容器，并注意设置 div 的 css 高宽样式（可以直接用内置样式mars3d-container），如下：

如下：

<div id="mars3dContainer" class="mars3d-container"></div>

4. 在相关组件中import导入SDK

安装后在相关使用组件文件中import导入SDK,并可增加如下代码，即可创建一个地图对象，并显示到页面中。

// 引入css
import "mars3d-cesium/Build/Cesium/Widgets/widgets.css"
import "mars3d/mars3d.css" // v3.8.6及之前版本使用 import "mars3d/dist/mars3d.css";

import * as mars3d from "mars3d"
import "mars3d-space" // 导入mars3d插件，导入即可，自动注册（按需使用，需要先npm install mars3d-space）
// import "mars3d-heatmap"; // 其他插件类型，自行修改名称

const Cesium = mars3d.Cesium 

// Map的参数请看API文档：http://mars3d.cn/api/Map.html
const map = new mars3d.Map("mars3dContainer", {
  basemaps: [{ name: "天地图", type: "tdt", layer: "img_d", show: true }]
})

5. 修改相关配置

因为 mars3d 所依赖的 Cesium 是一个多文件资源的 js 库，需要对其依赖的一些资源文件进行拷贝处理（这也是容易出问题的地方），所以需要修改相关配置。 90%的集成问题都是出现在对 cesium 库的拷贝处理上，项目运行没有正确识别 Cesium 主目录造成各种问题。

下面请根据你项目的技术栈，选择对应的集成方式。

5.1 webpack 技术栈时的项目配置修改

参考源码：https://gitee.com/marsgis/mars3d-vue-template
修改文件：webpack.config.js

关键代码及步骤：

安装依赖库（注意copy-webpack-plugin与webpack版本的依赖，可能需要按webpack对应版本的相关版本安装）

npm install copy-webpack-plugin --save-dev

修改 webpack.config.js 配置文件

const path = require("path")
const CopyWebpackPlugin = require("copy-webpack-plugin")
const webpack = require("webpack")

const cesiumSourcePath = "node_modules/mars3d-cesium/Build/Cesium/" // cesium库安装目录
const cesiumRunPath = "./mars3d-cesium/" // cesium运行时路径

module.exports = {
  module: {
    rules: [
      { test: /\.css$/, use: ["style-loader", "css-loader"] },
      { test: /\.js$/, use: { loader: "babel-loader", options: { plugins: ["@babel/plugin-proposal-class-properties"] } } }
    ]
  },
  plugins: [
    // CESIUM_BASE_URL是标识cesium资源所在的主目录，其内部资源加载、多线程等处理时需要用到
    new webpack.DefinePlugin({
      CESIUM_BASE_URL: JSON.stringify(cesiumRunPath)
    }),
    // Cesium相关资源目录需要拷贝到系统目录下面（部分CopyWebpackPlugin版本的语法可能没有patterns）
    new CopyWebpackPlugin({
      patterns: [
        { from: path.join(cesiumSourcePath, "Workers"), to: path.join(cesiumRunPath, "Workers") },
        { from: path.join(cesiumSourcePath, "Assets"), to: path.join(cesiumRunPath, "Assets") },
        { from: path.join(cesiumSourcePath, "ThirdParty"), to: path.join(cesiumRunPath, "ThirdParty") },
        { from: path.join(cesiumSourcePath, "Widgets"), to: path.join(cesiumRunPath, "Widgets") }
      ]
    })
  ]
}

提示

集成提示错误时，可看下"@vue/cli-service"的版本，需要是v5及以上版本，可以升级为："~5.0.0",否则建议您用静态方式集成Mars3D。

5.2 vue-cli 技术栈时的项目配置修改

参考项目：https://gitee.com/marsgis/mars3d-vue-template
修改文件：vue.config.js

关键代码及步骤：

安装依赖库（注意copy-webpack-plugin与webpack版本的依赖，可能需要按webpack对应版本的相关版本安装）

npm install copy-webpack-plugin --save-dev

修改 vue.config.js 配置文件

const path = require("path")
const CopyWebpackPlugin = require("copy-webpack-plugin")
const webpack = require("webpack")

module.exports = {
  configureWebpack: (config) => {
    const cesiumSourcePath = "node_modules/mars3d-cesium/Build/Cesium/" // cesium库安装目录
    const cesiumRunPath = "./mars3d-cesium/" // cesium运行时路径

    const plugins = [
      // 标识cesium资源所在的主目录，cesium内部资源加载、多线程等处理时需要用到
      new webpack.DefinePlugin({
        CESIUM_BASE_URL: JSON.stringify(path.join(config.output.publicPath, cesiumRunPath))
      }),
      // Cesium相关资源目录需要拷贝到系统目录下面（部分CopyWebpackPlugin版本的语法可能没有patterns）
      new CopyWebpackPlugin({
        patterns: [
          { from: path.join(cesiumSourcePath, "Workers"), to: path.join(config.output.path, cesiumRunPath, "Workers") },
          { from: path.join(cesiumSourcePath, "Assets"), to: path.join(config.output.path, cesiumRunPath, "Assets") },
          { from: path.join(cesiumSourcePath, "ThirdParty"), to: path.join(config.output.path, cesiumRunPath, "ThirdParty") },
          { from: path.join(cesiumSourcePath, "Widgets"), to: path.join(config.output.path, cesiumRunPath, "Widgets") }
        ]
      })
    ]

    return {
      module: { unknownContextCritical: false }, // 配置加载的模块类型，cesium时必须配置
      plugins
    }
  }
}

5.3 vite 技术栈时的项目配置修改

参考项目：https://gitee.com/marsgis/mars3d-vue-template
修改文件：vite.config.ts

关键代码及步骤：

安装依赖库

npm install vite-plugin-mars3d --save-dev

修改 vite.config.ts 配置文件

import { defineConfig } from "vite"
import { mars3dPlugin } from "vite-plugin-mars3d"

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

vite常见问题

使用原生cesium时，不要安装 mars3d-cesium（不能同时存在2个cesium 包），再在vite.config.ts配置改为 mars3dPlugin({ cesiumPackageName: "cesium" })
如果项目的 package.json 没有 type:"module" 或是vite4及之前版本时，请使用 "vite-plugin-mars3d":"~3.1.3"
如果项目的 package.json 有 type:"module" 直接用最新版本即可。
如果无法排除解决问题，也可以在vite.config.ts配置改为静态引入 mars3dPlugin({ useStatic: true })

可以在 import 引入 mars3d 的方式下，兼容识别 head 静态引入的 Cesium 库。

index.html增加静态引入mars3d-cesium

主要修改项目地图呈现对应的首页index.html页面，在其 head 中引入 cesium 资源，可以参考静态引入方式Mars3D中下载cesium资源到本地的步骤。

<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="./lib/Cesium/Cesium.js" type="text/javascript"></script>

修改配置，排除`mars3d-cesium`的引用和打包

在对应的技术栈配置中按技术栈的配置规则，排除mars3d-cesium的引用和打包。

vue.config.js

module.exports = {
  // 已忽略其他无关配置
  configureWebpack: {
    externals: { "mars3d-cesium": "Cesium" } // 排除使用 mars3d-cesium
  }
}

vite.config.ts

import { defineConfig } from "vite"
import { viteExternalsPlugin } from "vite-plugin-externals"

export default defineConfig({
  // 已忽略其他无关配置
  plugins: [
    viteExternalsPlugin({
      externals: { "mars3d-cesium": "Cesium" } // 排除使用 mars3d-cesium
    })
  ]
})

7.2 临时更新SDK为最新版本

如果mars3d官方临时修改SDK，但未发布最新npm正式包时，则可以通过在官网下载最新SDK,按以下方式更新mars3d最新开发版本。

方式 1：临时覆盖本地node_modules

该方式可用于临时更新本地node_modules中的mars3d包，但需要每次npm i 后覆盖一次。

将离线包的mars3d.js和mars3d.css文件覆盖到 \node_modules\mars3d\目录下同名文件。
下载链接：
http://mars3d.cn/lib/mars3d/mars3d.css
http://mars3d.cn/lib/mars3d/mars3d.js
http://mars3d.cn/lib/mars3d/mars3d.d.ts

覆盖后执行npm run clean-cache清理缓存（确保F12打印的编译日期是最新的），可在package.json中scripts节点下加上下面命令：

"clean-cache": "rimraf node_modules/.cache/ && rimraf node_modules/.vite",

方式 2：修改package.json的指向项目本地目录

此方式适合商业授权版 SDK 或想永久固化版本时使用，操作步骤：

在项目根目录创建/packages/目录
覆盖官网下载最新版：将mars3d-sdk.zip离线包放到packages目录，并解压到当前目录下，解压后packages的目录结构为：

mars3d-vue-project

packages

mars3d

img

mars3d.css

mars3d.d.ts

mars3d.js

package.json#必须有，如果没有请下载包中拷贝：http://mars3d.cn/download/mars3d-sdk.zip

修改链接：修改package.json中mars3d包配置为： "mars3d": "file:packages/mars3d",
【重要】删除node_modules重新npm install安装依赖

1.npm包安装方式集成到项目

1. 从 npm 安装获取SDK

3. 增加DIV展示容器

4. 在相关组件中import导入SDK

5. 修改相关配置

5.1 webpack 技术栈时的项目配置修改

5.2 vue-cli 技术栈时的项目配置修改

5.3 vite 技术栈时的项目配置修改

vite常见问题

6. 完成集成

7. 常见问题

7.1. 集成失败报错无法解决时

index.html增加静态引入mars3d-cesium

修改配置，排除`mars3d-cesium`的引用和打包

7.2 临时更新SDK为最新版本

方式 1：临时覆盖本地node_modules

方式 2：修改package.json的指向项目本地目录