pkgdown构建的R包网站本地正常，无法在GitHub Pages发布

1. 检查GitHub Pages基础配置 #

• 登录你的GitHub仓库，进入Settings → Pages
• 确认Source设置：
  • 分支选择gh-pages（如果之前用usethis命令尝试创建过），若该分支不存在，手动创建空分支：

    git checkout --orphan gh-pages
    git rm -rf .
    git commit --allow-empty -m "Initialize gh-pages branch"
    git push origin gh-pages
    

  • 根目录选择/(root)（对应gh-pages分支的根目录）

2. 手动执行pkgdown发布流程 #

不要仅依赖usethis::use_pkgdown_github_pages()，直接运行发布命令：

• 先确认本地构建正常：

  pkgdown::build_site()
  

• 将构建好的内容推送到GitHub Pages分支：

  pkgdown::deploy_to_branch(branch = "gh-pages")
  

3. 修复缺失的页面链接（Browse source code、Report a bug） #

这些链接由pkgdown根据包的DESCRIPTION文件自动生成，需确保文件中正确填写：

URL: https://github.com/InfiniteCuriosity/Ensembles
BugReports: https://github.com/InfiniteCuriosity/Ensembles/issues

填写完成后重新构建并发布即可显示对应链接。

4. 排查GitHub Actions部署状态 #

• 进入仓库的Actions选项卡，查看是否有pkgdown相关工作流运行
• 若工作流失败，查看日志定位问题：常见原因包括GitHub Actions权限不足（需确保工作流有读写分支权限）、构建依赖缺失（需在_pkgdown.yml或Actions配置文件中声明依赖）

5. 等待部署生效 #

GitHub Pages发布后通常需要5-10分钟生效，若网址无法访问，先确认仓库名大小写是否与网址一致（GitHub Pages对仓库名大小写敏感），再等待一段时间后刷新尝试。

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