用 cobe 撸一个 3D 地球，被糟糕的文档坑了之后我悟出的几点经验

在参加前端挑战赛的时候，我决定做一个名为 Comfort Atlas 的项目，把全球 100 个国家的“安慰食物”标注在地球上。原本打算用常规的 SVG 世界地图，但那种平面效果实在太单调，于是我尝试用一个轻量级的库 cobe 来实现 3D 效果。

在实际开发过程中，我发现 cobe 的文档简直是灾难，很多关键的运行时逻辑完全没写。如果你直接照着 README 里的示例代码写，最后渲染出来的结果大概率是一堆诡异的浮点数，而不是一个旋转的地球。

在通过 Claude Code 强行啃完它的源码后，我才发现一个极其低级的坑：createGlobe() 这个函数其实只负责绘制第一帧同步画面。如果你想要地球动起来，必须手动通过 requestAnimationFrame 去驱动 .update() 方法。

具体实现代码应该是这样的：

const globe = createGlobe(canvas, options);

function tick() {
  globe.update();
  requestAnimationFrame(tick);
}

requestAnimationFrame(tick);

这段逻辑在官方文档里几乎被忽略了，但如果不写，你的地球永远是静止的。这让我意识到，在面对文档缺失的开源库时，让 AI 直接分析源码比翻文档要高效得多。

除了解决渲染问题，这个项目里最让我头疼的是两个没有库支持的自定义功能。第一个是 Tooltip 的实时跟随。因为 3D 标记点是在 Canvas 内部绘制的，而 Tooltip 是 DOM 元素，我必须把 3D 空间中的坐标实时投影到 2D 屏幕平面上，才能让提示框精准地跟着标记点走。

第二个挑战是在已访问的国家之间绘制一条淡出的大圆航线（Great Circle Route）。由于 cobe 并没有内置路径绘制 API，我不得不手动处理球面到平面的投影矩阵。在这个过程中，我让 AI 帮我逐行解释数学公式，然后我自己用 JS 重新实现了一遍。虽然过程痛苦，但把投影矩阵跑通的那一刻，成就感比吃到正宗的意大利面还要强。

目前这个版本还加入了一个“今日推荐菜（Feature Dish of the Day）”的功能，通过一套确定性算法，确保全球访客在同一天看到的菜品是一致的。另外，我还设计了一个护照印章风格的卡片生成器，用户输入自己的 Comfort Dish 后，可以生成三种不同配色的卡片并下载。

不过，这个项目也给我留了一个深刻的教训：Canvas 的无障碍访问（a11y）比 DOM 难做太多。虽然我部署在 Netlify 上后进行了多次键盘导航测试，但依然发现某些交互点在屏幕阅读器下不够友好。对于追求极致体验的开发者来说，单纯依赖 Canvas 绘制 3D 场景，在可访问性上确实需要付出比平时多出数倍的努力。

最后分享一个细节，这个项目目前是 MIT 开源的。虽然我在地图里标注了希腊的 Moussaka，但作为一个希腊人，我其实更喜欢披萨。