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

2280字约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.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的指向项目本地目录