GitHub Pages 长期运维清单

仓库设置

GitHub Pages 建议统一使用 GitHub Actions 部署，避免手动维护 gh-pages 分支。进入仓库的 Settings -> Pages，将 Build and deployment 设置为 GitHub Actions。

路径配置

用户主页仓库通常部署在根路径：

SITE=https://xhioer.github.io
BASE_PATH=/

如果后续使用项目仓库部署，则需要给资源路径加上仓库名前缀：

SITE=https://xhioer.github.io
BASE_PATH=/xhioer.github.io

域名与 HTTPS

如果绑定自定义域名，在仓库 Pages 设置里填写域名并勾选 HTTPS。DNS 侧添加 CNAME 到 xhioer.github.io，根域名可以按 GitHub Pages 官方文档配置 A/AAAA 记录。

常见排查

• 样式或图片丢失：检查 BASE_PATH 是否和仓库部署路径一致。
• 搜索不可用：确认构建脚本执行了 pagefind --site dist。
• Sitemap 地址错误：确认 SITE 环境变量和 site 配置指向最终线上地址。
• Actions 没有权限：检查仓库 Settings -> Actions -> General 的 workflow permissions。