GitHub Pages部署的React网站首次进入时背景媒体加载异常求助

1. 修正静态资源引用路径 #

GitHub Pages部署时，静态资源的基础路径是你的仓库名称（即/react-portfolio/），如果直接用相对路径或根路径引用资源，首次加载会出现路径匹配错误：

• 先在package.json中添加主页配置：

  "homepage": "/react-portfolio/"
  

• 引用资源时用process.env.PUBLIC_URL拼接路径，示例：

  <video src={`${process.env.PUBLIC_URL}/video/background.webm`} autoPlay loop muted />
  <img src={`${process.env.PUBLIC_URL}/images/card-item.jpg`} alt="card content" />
  

2. 配置React Router的basename #

如果使用了React Router，未设置basename会导致路由跳转后资源路径才正确，首次加载出错：

• 在Router组件中添加basename属性，值为仓库名：

  import { BrowserRouter as Router } from 'react-router-dom';
  
  function App() {
    return (
      <Router basename="/react-portfolio">
        {/* 路由内容 */}
      </Router>
    );
  }
  

3. 预加载关键资源 #

首次加载时浏览器优先加载JS/CSS，可能阻塞视频和图片加载，可通过预加载标签强制优先加载：

• 在public/index.html的<head>中添加：

  <link rel="preload" href="%PUBLIC_URL%/video/background.webm" as="video" type="video/webm">
  <link rel="preload" href="%PUBLIC_URL%/images/your-card-image.jpg" as="image">
  

• 也可以给资源标签添加loading="eager"属性，示例：

  <video loading="eager" src={`${process.env.PUBLIC_URL}/video/background.webm`} ... />
  

4. 处理缓存问题 #

GitHub Pages可能缓存旧资源，即使重新部署也残留：

• 确保Create React App构建时给静态资源自动添加哈希后缀（默认已开启），保证每次部署的资源文件名唯一。
• 测试时用浏览器隐私模式打开，避免本地缓存干扰。

5. 兼容视频格式 #

.webm虽体积小，但部分浏览器对编码有要求，建议添加MP4作为 fallback，避免兼容性导致加载失败：

<video autoPlay loop muted>
  <source src={`${process.env.PUBLIC_URL}/video/background.webm`} type="video/webm">
  <source src={`${process.env.PUBLIC_URL}/video/background.mp4`} type="video/mp4">
</video>

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