VS Code本地可正常运行的网站部署至Git Pages后显示异常

我正在开发第一个HTML/CSS/JS小型项目：

• 本地VS Code环境中网站显示完全正常
• 通过Git Pages部署后显示异常，控制台提示无法找到其他资源文件
• 本地与GitHub仓库的文件路径一致，尝试过Git推拉操作偶尔能成功，但推测是文件夹路径问题；之后改为手动上传代码，导致提交记录杂乱
• 之前遇到过README文件优先发布而非HTML文件的问题，将README移至其他文件夹后已解决

仓库地址：l-antonello/prework-study-guide
网站地址：l-antonello.github.io/prework-study-guide

1. 统一使用相对路径引用资源 #

Git Pages部署后网站根路径为仓库名称（即/prework-study-guide/），本地绝对路径（如/css/style.css）会导致资源找不到：

• 所有资源引用改用相对路径：
  • CSS文件：./css/style.css
  • JS文件：./js/script.js
• 避免以/开头的绝对路径，除非明确基于仓库根目录写全路径（如/prework-study-guide/css/style.css，但灵活性差）

2. 核对Git Pages部署源设置 #

进入GitHub仓库「Settings」→「Pages」：

• 确认「Source」选择了正确分支（通常是main或master）
• 检查「Folder」是否为/(root)（若入口HTML在仓库根目录），或对应存放HTML的子目录
• 确保入口HTML文件（如index.html）在部署目录下，且是该目录的默认首页文件

3. 整理Git提交记录（可选） #

手动上传导致提交杂乱，可通过以下命令重置（注意：会覆盖远程记录，谨慎操作）：

# 重置到干净的提交节点，替换<commit-hash>为目标提交哈希值
git reset --hard <commit-hash>
# 强制推送到远程仓库
git push origin main --force

之后建议用VS Code Git插件或命令行执行推拉，避免手动上传引发的同步问题。

4. 强制刷新缓存 #

Git Pages可能缓存旧内容，可通过两种方式触发更新：

• 浏览器按Ctrl + Shift + R（Windows/Linux）或Cmd + Shift + R（Mac）强制刷新页面
• 进入仓库「Pages」设置页，重新保存部署配置，触发重新构建

5. 检查文件大小写一致性 #

Windows路径不区分大小写，但Git Pages运行在Linux环境下大小写敏感：

• 确保本地文件名、文件夹名与代码中引用的路径大小写完全匹配（如CSS和css会被视为不同文件夹）

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