为何我的Three.js网站动画本地正常但GitHub Pages无法显示？

开发者阿泽

2026-10-2

问题原因

本地运行时资源根路径是项目本地根目录，部署到GitHub Pages后，站点默认挂载在仓库名对应的子路径下，代码中的绝对路径、相对路径配置不匹配，导致脚本或纹理资源加载失败，动画无法渲染。

修复步骤

调整所有资源引用为相对路径

HTML文件中，把main.js的引用从<script type="module" src="/main.js"></script>改为<script type="module" src="./main.js"></script>，favicon路径从/favicon.svg改为./favicon.svg

JS文件中，修改纹理加载路径：

// 原代码
const blacktexture = new THREE.TextureLoader().load('black-screen.jpg');
const moonTexture = new THREE.TextureLoader().load('moon.jpg');
// 修改后
const blacktexture = new THREE.TextureLoader().load('./black-screen.jpg');
const moonTexture = new THREE.TextureLoader().load('./moon.jpg');

调整打包配置适配子路径部署
如果你使用Vite作为构建工具，在项目根目录的vite.config.js中添加base配置，值为你的GitHub仓库名（前后加斜杠）：
```
export default defineConfig({
  base: '/你的仓库名/',
  // 其余原有配置
})
```
正确部署静态资源
1. 所有静态资源（black-screen.jpg、moon.jpg、favicon.svg等）统一放在项目的public目录下，打包时会自动复制到dist文件夹
2. 不要手动创建dist文件夹，运行npm run build自动生成打包产物，将dist目录下的所有内容推送到GitHub Pages的gh-pages分支即可。