推HTML文件至github.io后CSS丢失，Sphinx文档样式异常如何修复？

常见原因及修复步骤 #

1. 修正Sphinx配置中的html_baseurl #

打开Sphinx项目的conf.py文件，添加或修改html_baseurl配置，值设为你的GitHub Pages域名：

html_baseurl = "https://jodyxha.github.io/"

保存后重新生成文档（执行make html），再将build/html下的所有内容复制到github.io本地仓库，重新提交推送。

2. 强制生成相对路径的资源引用 #

如果不想固定html_baseurl，可以在生成文档时添加--relative-links参数，确保静态资源用相对路径引用：

make html BUILDDIR=build/html SPHINXOPTS="--relative-links"

生成完成后再同步文件到github.io仓库。

3. 检查GitHub Pages仓库设置 #

• 进入jodyxha.github.io仓库的Settings -> Pages页面
• 确认Source选择的是你推送代码的分支（比如main），且目录选择/(root)
• 等待5-10分钟让GitHub Pages重新部署，避免缓存导致的样式不生效

4. 确认静态资源完整上传 #

检查远程仓库的代码，确保_static目录完整存在，CSS、JS等文件没有缺失。如果之前复制时遗漏了子目录，重新执行以下操作：

# 进入Sphinx项目目录
cd /path/to/your/sphinx/project
# 重新生成文档
make html
# 完整复制到github.io仓库
cp -r build/html/* /path/to/jodyxha.github.io/
# 提交推送
cd /path/to/jodyxha.github.io/
git add .
git commit -m "Update docs with complete static assets"
git push origin main

5. 强制刷新浏览器缓存 #

按Ctrl + Shift + R（Windows/Linux）或Cmd + Shift + R（Mac）强制刷新页面，加载最新的样式文件，避免浏览器缓存旧页面。

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