three-earth-3d

基于 Three.js 构建的 3D 地球可视化组件，可挂载到任意 DOM 元素上。

本项目由 GhostCatcg/3d-earth 改造而来，在其基础上迁移至 Vite 构建体系，并以 npm 包的形式发布，支持在任意前端项目中实例化多个独立的 3D 地球。

English README

功能特性

• 🌏 地球贴图 + 扫光 Shader 动画
• ✨ 辉光、大气层效果
• 🛰 卫星轨道环绕
• 🇨🇳 城市标点 + 城市标签（html2canvas 渲染）
• 🪐 城市间弧线飞线
• 🎛 全部参数可配置，支持自定义数据
• 🔧 提供 dispose() 方法，干净销毁实例

安装

# pnpm
pnpm add three-earth-3d three

# npm
npm install three-earth-3d three

# yarn
yarn add three-earth-3d three

three 为 peerDependency，需要单独安装，支持 three >= 0.130.0。

快速上手

1. 准备静态资源

包内提供了一个 CLI 工具，一条命令即可将所有贴图复制到你项目的 public/ 目录：

# 复制到 ./public/images/earth/（默认）
npx three-earth-3d

# 或指定目标目录（例如 Nuxt / SvelteKit 的 static/）
npx three-earth-3d --dest static

执行后目录结构如下：

public/
└── images/
    └── earth/
        ├── earth.jpg        ← 地球贴图（主要素材，约 2.4 MB）
        ├── glow.png
        ├── gradient.png
        ├── aperture.png
        ├── label.png
        ├── light_column.png
        ├── redCircle.png
        └── aircraft.png

为什么不内置到 JS 里？
earth.jpg 约 2.4 MB，base64 内联后会让 bundle 膨胀到 ~3 MB，得不偿失。
独立部署贴图可以被浏览器缓存，也更容易替换成自定义地球图。

2. HTML 结构

容器需要有明确的宽高，地球会撑满容器：

<div id="earth-canvas" style="width: 100%; height: 100vh; background: #010826;"></div>

3. 初始化

import { World } from 'three-earth-3d'

const world = new World({
  dom: document.getElementById('earth-canvas'),
  // 图片所在的基础路径（相对或绝对），对应 /images/earth/ 的上级
  // 例如图片放在 /public/images/earth/，baseUrl 填 '' 或 '/'
  baseUrl: '',
  onReady() {
    console.log('地球加载完成！')
  },
})

4. 销毁

world.dispose()

完整配置项

import { World } from 'three-earth-3d'

const world = new World({
  /** 必填：挂载的 DOM 元素 */
  dom: document.getElementById('earth-canvas'),

  /**
   * 静态图片资源根路径
   * 组件会在 `${baseUrl}/images/earth/` 下加载图片
   * 默认值：''（即从网站根路径 /images/earth/ 加载）
   */
  baseUrl: '',

  /** 地球初始化并开始入场动画后触发 */
  onReady: () => { console.log('ready') },

  /**
   * 自定义航线数据，不传则使用内置示例数据（北京/杭州为起点的航线）
   * 每一条记录包含一个起点和多个终点
   */
  data: [
    {
      startArray: { name: '北京', E: 116.322056, N: 39.89491 },
      endArray: [
        { name: '上海', E: 121.473701, N: 31.230416 },
        { name: '广州', E: 113.264385, N: 23.129112 },
      ],
    },
  ],

  /** 地球参数 */
  earth: {
    radius: 50,          // 地球半径，默认 50
    rotateSpeed: 0.002,  // 自转速度，默认 0.002
    isRotation: true,    // 是否自转，默认 true
  },

  /** 卫星参数 */
  satellite: {
    show: true,          // 是否显示卫星，默认 true
    rotateSpeed: -0.01,  // 轨道旋转速度，默认 -0.01
    size: 1,             // 卫星球体大小，默认 1
    number: 2,           // 每条轨道的卫星数量，默认 2
  },

  /** 标点和光柱参数 */
  punctuation: {
    circleColor: 0x3892ff,    // 底座圆圈颜色
    lightColumn: {
      startColor: 0xffffff,   // 起点光柱颜色
      endColor: 0xff0000,     // 终点光柱颜色
    },
  },

  /** 飞线参数 */
  flyLine: {
    color: 0xd18547,          // 轨迹线颜色
    speed: 0.004,             // 飞线拖尾运动速度
    flyLineColor: 0xff7714,   // 飞线自身颜色
  },
})

API

new World(options: IWord)

创建一个 3D 地球实例并挂载到指定 DOM。

world.dispose()

销毁实例，释放 WebGL 上下文、停止动画循环、移除 DOM 元素及监听器。在 SPA 框架中切换路由时务必调用。

在框架中使用

Vue 3

<template>
  <div ref="earthEl" class="earth-container" />
</template>

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { World } from 'three-earth-3d'

const earthEl = ref<HTMLElement | null>(null)
let world: World | null = null

onMounted(() => {
  world = new World({
    dom: earthEl.value!,
    baseUrl: '',
  })
})

onBeforeUnmount(() => {
  world?.dispose()
})
</script>

<style scoped>
.earth-container {
  width: 100%;
  height: 100vh;
  background: #010826;
}
</style>

React

import { useEffect, useRef } from 'react'
import { World } from 'three-earth-3d'

export default function EarthView() {
  const containerRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    const world = new World({
      dom: containerRef.current!,
      baseUrl: '',
    })
    return () => world.dispose()
  }, [])

  return (
    <div
      ref={containerRef}
      style={{ width: '100%', height: '100vh', background: '#010826' }}
    />
  )
}

本地开发

# 克隆
git clone https://github.com/adoin/three-earth-3d.git
cd three-earth-3d

# 安装依赖
pnpm install

# 启动开发服务器（访问 http://localhost:5173）
pnpm dev

# 构建库产物（输出到 dist/）
pnpm build

# 构建 demo 并预览生产效果（访问 http://localhost:4173）
pnpm preview

注意事项

1. 图片资源：组件本身不内置图片，需要将 static/images/earth/ 下的素材部署到你的 public 或 CDN，并通过 baseUrl 指向其上级路径。

2. 容器尺寸：挂载的 DOM 必须有确定的宽高，否则渲染尺寸为 0。

3. 多实例：每个 new World() 会创建独立的 WebGL 上下文，注意浏览器对同时存在的 WebGL 上下文数量有限制（通常 8~16 个），请在不需要时及时调用 dispose()。

致谢

本项目基于 GhostCatcg/3d-earth 改造，感谢原作者 GhostCat 的创意与实现。

主要改动：

• 构建工具从 Webpack 迁移至 Vite，支持库模式打包
• 以 npm 包形式发布，可在任意项目中通过 new World({ dom }) 实例化
• 资源路径由硬编码改为可配置的 baseUrl
• 挂载容器改用 dom.offsetWidth/Height 而非全局 window 尺寸
• 新增 onReady 回调、dispose() 方法及完整 TypeScript 类型导出

License

MIT