Cesium实战：如何正确添加Token指令以解决地图加载授权问题

1次阅读

共计 3280 个字符，预计需要花费 9 分钟才能阅读完成。

Cesium Ion 服务的所有 3D 地理空间数据（如地形、影像、3D 模型）都要求通过 AccessToken 进行身份验证。其本质是 OAuth2.0 的 Bearer Token 机制，每个 Token 关联着：

账户配额限制（如每月 100GB 流量）
授权资源范围（如特定资产 ID）
时效性（默认 1 年有效期）

当浏览器发起瓦片请求时，Cesium 会自动在请求头添加 Authorization: Bearer xxx。若未配置或 Token 无效，控制台会出现401 Unauthorized 错误并伴随 ion-xxx 前缀的警告信息。

最基础的配置方式，适用于单 Token 应用场景：

// 建议在应用初始化时最早执行
Cesium.Ion.defaultAccessToken = 'your_token_here';

特点：
– 所有通过 Cesium.createXXX 创建的资源自动继承该 Token
– 会污染全局状态，不适合多租户系统

更推荐的模块化配置方式：

const viewer = new Cesium.Viewer('cesiumContainer', {
  imageryProvider: new Cesium.IonImageryProvider({ 
    assetId: 3845,
    accessToken: 'specific_token_here' 
  }),
  terrainProvider: Cesium.createWorldTerrain({
    requestWaterMask: true,
    requestVertexNormals: true
  }) // 自动使用 defaultAccessToken
});

优势：
– 不同图层可使用不同 Token
– 清晰的责任链，便于调试

适用于按需加载场景：

const dynamicTileset = await Cesium.Cesium3DTileset.fromIonAssetId(12345, {
  accessToken: 'dynamic_token_here',
  showOutline: true
});
viewer.scene.primitives.add(dynamicTileset);

安装依赖：

npm install dotenv @types/dotenv

创建 .env 文件：

VITE_CESIUM_TOKEN=your_actual_token

TypeScript 集成：

import {config} from 'dotenv';
config();

// 使用 vite 环境变量需配置 vite.config.ts
const cesiumToken = import.meta.env.VITE_CESIUM_TOKEN;

if (!cesiumToken) {throw new Error('Missing Cesium Token in env vars');
}

/**
 * 安全获取 Token 的封装方法
 * @param fallback 降级使用的默认 Token
 */
function getSafeToken(fallback?: string): string {
  try {return cesiumToken || fallback || '';} catch (error) {console.warn('Token 加载失败', error);
    return fallback || '';
  }
}

建议实现 Token 失效时的三级降级方案：

主 Token → 2. 备用 Token → 3. 本地模拟数据

class TokenManager {private static backupTokens = ['token2', 'token3'];

  /**
   * 处理 ION 请求错误
   * @param error Cesium.IonError
   */
  static async handleIonError(error: any) {if (error?.statusCode === 401) {const nextToken = this.backupTokens.pop();
      if (nextToken) {
        Cesium.Ion.defaultAccessToken = nextToken;
        console.warn('自动切换备用 Token');
        await this.retryLoading();} else {this.showFallbackMap();
      }
    }
  }

  private static showFallbackMap() {
    viewer.imageryProvider = new Cesium.TileMapServiceImageryProvider({url: Cesium.buildModuleUrl('Assets/Textures/NaturalEarthII')
    });
  }
}

当使用 CDN 或跨域代理时，需确保：

代理服务器转发 Authorization 头
配置 CORS 响应头：

Access-Control-Allow-Headers: authorization
Access-Control-Allow-Credentials: true

建议采用策略模式封装 Token 管理：

class TenantTokenManager {private tokenMap = new Map<string, string>();

  register(tenantId: string, token: string) {this.tokenMap.set(tenantId, token);
  }

  activate(tenantId: string) {const token = this.tokenMap.get(tenantId);
    if (token) {
      Cesium.Ion.defaultAccessToken = token;
      return true;
    }
    return false;
  }
}

// 使用示例
const tokenManager = new TenantTokenManager();
tokenManager.register('clientA', 'token_A');
tokenManager.register('clientB', 'token_B');

// 根据用户身份切换
tokenManager.activate(currentUser.tenant);

通过拦截请求实现用量统计：

const originalLoad = Cesium.Resource.prototype.fetch;
Cesium.Resource.prototype.fetch = function() {const startTime = Date.now();
  return originalLoad.apply(this, arguments).then(response => {const contentLength = response.headers.get('content-length');
    trackUsage({
      url: this.url,
      size: parseInt(contentLength || '0'),
      duration: Date.now() - startTime});
    return response;
  });
};