Docusaurus部署至组织GitHub Pages访问404如何解决

核心结论 #

部署到组织账号名下的仓库时，GITHUB_USER参数必须填写组织账号名称，不能填写执行部署操作的个人账号名。该参数的作用是指定GitHub Pages所属的命名空间，和部署操作使用的账号身份无关，只要执行部署的个人账号拥有目标组织仓库的推送权限即可正常操作。

分步排查解决流程 #

• 修正docusaurus.config.js配置
  • 将url字段值设置为https://<组织GitHub账号名>.github.io，不要拼接仓库名后缀
  • 将baseUrl字段值设置为/<目标仓库名>/，路径前后的斜杠不能省略
  • 若配置中存在organizationName字段，值必须填写组织账号名；projectName字段填写对应仓库的名称
• 修正部署命令
  部署时将GITHUB_USER参数替换为组织账号名，标准命令格式为：

  GITHUB_USER=<组织GitHub账号名> yarn deploy
  

  之前填入个人用户名执行部署时，脚本实际会将构建产物推送到你个人账号下同名仓库的gh-pages分支，而非组织仓库的对应分支，这也是提示部署成功但组织域名访问404的核心原因。

  注意：部署脚本返回的“站点已上线”提示是根据本地配置拼接的静态文本，不会实际校验构建产物是否推送到了正确的仓库分支，不能作为部署成功的判断依据。

• 检查仓库Pages配置
  进入组织下目标仓库的Settings -> Pages页面：
  • 确认Source源选择为gh-pages分支，部署目录选择根目录/ (root)
  • 确认组织未限制仓库的Pages功能，部分组织会默认关闭成员自主配置Pages的权限，需要联系组织管理员确认开启
• 验证部署结果
  执行正确部署命令后，先在仓库分支列表确认存在gh-pages分支，且分支内包含构建生成的index.html及对应静态资源文件。等待1-2分钟待GitHub完成Pages缓存刷新后，再访问对应站点地址即可，刚推送完构建产物立刻访问可能出现临时404。

内容的提问来源于stack exchange，提问作者Kürşat Şimşek