部署React应用到GitHub Pages后public文件夹图片加载失败求助

问题核心 #

部署到GitHub Pages后，public文件夹内的图片通过react-three-fiber的useLoader钩子加载失败，控制台报错：

Uncaught Error: Could not load /{myrepo}{folderName}/{the-image}.jpeg: undefined)
 at index-6f0019d1.esm.js:1670:1

尝试过直接写路径、用process.env.PUBLIC_URL拼接均无效，下面解释关键原因和解决方法。

原因拆解 #

GitHub Pages部署的React应用是放在子路径下的（比如https://xxx.github.io/your-repo/），而非根域名。Three.js的TextureLoader路径解析逻辑和React静态资源不同：React的PUBLIC_URL会自动带上仓库名，但TextureLoader默认从页面根路径（/）请求资源，若拼接路径时少了斜杠，就会出现repo-namefolderName这种错误路径，导致资源找不到。

解决步骤 #

1. 配置package.json的homepage #

先在项目根目录的package.json里添加homepage字段，两种写法都可以：

• 明确指定仓库地址：

"homepage": "https://<你的GitHub用户名>.github.io/<你的仓库名>/"

• 通用相对路径写法（推荐，适配本地和部署环境）：

"homepage": "./"

这个配置会让React正确设置process.env.PUBLIC_URL的值，避免路径解析混乱。

2. 正确拼接加载路径 #

两种有效写法，选一种即可：

写法一：用相对路径（最简单）

直接以./开头写相对路径，对应public文件夹下的结构：

const [theImage, secondImage] = useLoader(TextureLoader, [
  "./folderName/the-image.jpeg",
  "./folderName/second-image.jpeg"
])

写法二：用process.env.PUBLIC_URL正确拼接

注意在PUBLIC_URL和文件夹名之间加斜杠，避免路径连在一起：

const basePath = `${process.env.PUBLIC_URL}/`;
const [theImage, secondImage] = useLoader(TextureLoader, [
  `${basePath}folderName/the-image.jpeg`,
  `${basePath}folderName/second-image.jpeg`
])

本地开发时process.env.PUBLIC_URL是空字符串，拼接后就是./folderName/...；部署后会自动带上仓库名，变成/repo-name/folderName/...，符合GitHub Pages的路径要求。

3. 确认部署命令正确 #

用gh-pages包部署时，确保打包和部署命令正确：
在package.json的scripts里配置：

"scripts": {
  "build": "react-scripts build",
  "deploy": "gh-pages -d build"
}

然后运行npm run build && npm run deploy完成部署。

为什么之前的尝试失败？ #

你之前用process.env.PUBLIC_URL + "{folderName}/{the-image}.jpeg"时，没有在PUBLIC_URL和文件夹名之间加斜杠，导致拼接后的路径变成/repo-namefolderName/the-image.jpeg（正确路径应该是/repo-name/folderName/the-image.jpeg），加载器自然找不到资源。

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