GitHub Pages嵌入MP4视频无法加载问题求助

问题概述 #

首次通过GitHub Pages部署网站，所有嵌入MP4均显示黑屏且控件置灰，本地测试正常，控制台无404或网络报错，排除Git LFS影响（仅143MB大文件使用LFS，小文件同样出问题）。

排查与解决步骤 #

1. 强制转码为标准MP4编码

GitHub Pages的静态文件服务对视频编码有严格要求，本地播放器兼容性强，但浏览器在服务器环境下仅支持标准编码。必须确保视频采用H.264视频编码 + AAC音频编码的MP4格式。
使用FFmpeg转码的命令示例：

ffmpeg -i 原视频文件.mp4 -c:v libx264 -c:a aac -strict -2 转码后视频文件.mp4

替换原视频文件后重新提交部署。

2. 校验文件路径与大小写

GitHub Pages区分文件名大小写，而本地Windows/macOS系统可能不区分。检查HTML中src属性的路径（如./assets/knowPros_Demo.mp4）是否与仓库中实际文件的路径、大小写完全一致，避免隐性路径错误。

3. 重新提交视频文件确保完整性

二进制文件在Git提交过程中可能出现损坏，尤其是大文件。执行以下步骤重新提交：

# 替换为转码后的视频文件
git add assets/*.mp4
git commit -m "fix: re-add encoded video files"
git push

提交完成后手动触发GitHub Pages重新部署（仓库Settings -> Pages -> 点击"Deploy branch"）。

4. 添加preload属性优化加载逻辑

部分浏览器在GitHub Pages环境下默认不预加载视频元数据，导致控件置灰。给video标签添加preload="metadata"属性：

<video class="responsive-video" id="knowPros_vid" controls preload="metadata">
    <source src="./assets/knowPros_Demo.mp4" type="video/mp4">
    Your browser does not support the video tag.
</video>

5. 规范Git LFS配置（针对大文件）

若使用Git LFS托管大视频，需确保：

• 仓库已开启GitHub LFS存储（仓库Settings -> LFS）
• 添加.gitattributes文件并配置：

*.mp4 filter=lfs diff=lfs merge=lfs -text

提交.gitattributes文件后重新推送大文件。

总结 #

优先排查视频编码兼容性问题，这是此类场景下最常见的根源。若以上步骤均无效，再考虑外部视频托管作为备选方案。

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