基于Three.js/React的3D地形飞行模拟器部署至GitHub Pages空白问题

先澄清一个误解 #

代码行数超过2000行不会直接导致部署后白屏，现代浏览器和托管平台完全支持处理大体积代码，问题根源大概率在路径配置、资源加载、生产环境编译差异这类环节。

具体排查步骤 #

1. 优先查看浏览器控制台报错 #

打开部署后的页面，按F12进入开发者工具，重点看两个面板：

• Console面板：捕获JS语法错误、资源加载失败、权限问题等直接报错信息，这是定位问题最快的方式
• Network面板：检查所有静态资源（JS/CSS/3D纹理/Shader文件）的加载状态，确认是否存在404或加载超时

2. 修正React项目的部署路径配置 #

• 如果是Create React App创建的项目，部署到GitHub Pages时必须在package.json中添加"homepage": "."（或对应仓库的完整路径，比如"homepage": "/abingandabong.github.io/"）
• 若使用React Router，部署到非根域名路径时，需给路由组件设置basename属性：

  <BrowserRouter basename="/abingandabong.github.io">
    {/* 路由内容 */}
  </BrowserRouter>
  

3. 排查开发/生产环境的编译差异 #

本地运行的是开发模式（npm start），部署的是生产编译后的代码（npm run build），两者可能存在逻辑差异：

• 检查代码中是否依赖process.env.NODE_ENV这类开发环境变量，生产环境下该变量值为production，若判断逻辑有误可能导致功能失效
• 确认3D相关依赖（比如Three.js）是否被正确打包，避免Tree Shaking误删核心功能代码

4. 校验静态资源加载路径 #

项目中3D地形生成依赖的Shader文件、纹理图等静态资源，若使用相对路径，部署后可能因目录结构变化无法加载：

• Create React App中需用process.env.PUBLIC_URL拼接资源路径，例如：

  const shaderUrl = `${process.env.PUBLIC_URL}/shaders/terrain.glsl`;
  

• 避免使用绝对路径（比如/shaders/xxx），除非部署在域名根目录

5. 优化生产包体积（辅助排查） #

虽然行数不是问题，但过大的单文件可能导致加载超时：

• 执行npm run build后查看build目录下的static/js文件大小，若单个文件超过1MB，建议开启代码分割，将3D模块单独拆分
• 使用npm run build -- --stats生成构建分析报告，定位未优化的大依赖包

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