部署React项目到Github Pages时public文件夹静态资源404问题求助

问题原因 #

你提到的绝对路径引用写法是引发404的核心原因。GitHub Pages 默认的项目部署路径为https://<用户名>.github.io/<仓库名>/，而非域名根路径。直接使用<img src="/barbell.svg">的写法会向根路径发起资源请求，实际资源存放在仓库对应的子路径下，因此匹配不到资源返回404。

解决方案 #

1. 配置项目路径前缀 #

打开项目根目录的package.json文件，新增homepage字段，填写你的GitHub Pages部署地址：

{
  "name": "你的项目名",
  "version": "0.1.0",
  "homepage": "https://<你的用户名>.github.io/<你的仓库名>/",
  // 其余原有配置保持不变
}

该配置会让项目构建时自动为所有静态资源添加正确的路径前缀。

2. 调整资源引用方式 #

两种可选写法，均可以自动适配开发、生产环境的路径：

• 保留public文件夹存放资源的话，使用process.env.PUBLIC_URL拼接路径：

<img src={`${process.env.PUBLIC_URL}/barbell.svg`} alt="杠铃图标" />

• 也可以将资源迁移到src目录下，通过导入的方式使用：
  将资源放到src/assets文件夹中，在组件内直接导入后引用：

// 导入资源
import barbellSvg from './assets/barbell.svg'
import testPdf from './assets/test.pdf'

// 组件内使用
<img src={barbellSvg} alt="杠铃图标" />
<a href={testPdf} target="_blank" rel="noopener noreferrer">查看PDF</a>

该方式由webpack自动处理路径，无需手动维护前缀，出错概率更低。

3. 重新构建部署 #

配置修改完成后，重新执行构建命令：

npm run build

确认build文件夹内的资源引用路径已添加仓库名前缀后，重新部署到GitHub Pages即可。

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