Three.js场景本地正常，GitHub Pages上TextGeometry不显示问题

这种本地跑完全正常，一部署到GitHub Pages就掉链子的问题真的让人头疼，尤其是只有TextGeometry出问题的时候！我之前也踩过类似的坑，给你列几个最可能的排查方向，按优先级来：

1. 字体文件的路径或存在性问题 #

这是最常见的原因，毕竟本地服务器和GitHub Pages的路径解析逻辑有差异：

• 先查文件是否真的推到GitHub了：打开你的GitHub仓库，确认字体文件（比如helvetiker_regular.typeface.json这类）有没有出现在对应的文件夹里。很容易不小心把fonts/文件夹加到.gitignore里，导致本地有文件但线上缺失。
• 检查路径大小写：Mac的文件系统不区分大小写，但GitHub Pages是区分的！比如你代码里写的./fonts/Helvetiker_Regular.typeface.json，但实际文件名是helvetiker_regular.typeface.json，本地能正常加载，线上直接就404了。
• 调整相对路径适配GitHub Pages子路径：如果你的GitHub Pages是基于仓库名的子路径（比如https://your-username.github.io/your-repo-name/），那相对路径可能需要调整。比如本地用./fonts/xxx.json，线上要改成/your-repo-name/fonts/xxx.json，或者用../层级来对应，具体看你的文件结构。
• 用浏览器开发者工具验证：F12打开开发者工具，切换到Network标签，刷新页面后找字体文件的请求。如果状态码是404，那就是路径或者文件存在性的问题；如果是200但还是不显示，再往下看。

2. Three.js版本或模块引入问题 #

TextGeometry在Three.js的新版本里有过结构调整：

• 确认TextGeometry的引入方式：从r139版本开始，TextGeometry不再是核心模块的一部分，需要单独引入addons里的版本。如果本地用的是新版本，线上却引用了旧的CDN链接，或者引入方式不对，就会出现THREE.TextGeometry is not defined的错误（看Console标签有没有这个提示）。
  正确的引入方式应该是：

  import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';
  import { FontLoader } from 'three/addons/loaders/FontLoader.js';
  

  如果是用CDN，要确保链接包含addons的路径，比如：

  <script src="https://cdn.jsdelivr.net/npm/three@0.158.0/build/three.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/geometries/TextGeometry.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/loaders/FontLoader.js"></script>
  

• 本地和线上版本一致：别本地用的是npm安装的最新版，线上却用了旧的CDN链接，版本差异很容易导致这类兼容性问题。

3. 浏览器控制台的错误提示是关键 #

不管上面哪条，首先去看浏览器的Console标签！任何加载失败、变量未定义的错误都会在这里显示。比如：

• 如果是Failed to load resource: the server responded with a status of 404 (Not Found)：直奔路径/文件存在性问题。
• 如果是Uncaught ReferenceError: TextGeometry is not defined：检查Three.js版本和引入方式。
• 如果是Cross-Origin Request Blocked：虽然GitHub Pages一般不会有CORS问题，但可以确认字体文件的MIME类型是否正确（JSON文件的MIME类型应该是application/json）。

先从控制台的错误入手，基本上能定位80%的问题！

内容的提问来源于stack exchange，提问作者Braden