使用GitHub Content API创建或更新文件时返回404错误的问题咨询

以下是开发过程中最常触发404错误的场景，可按顺序逐一排查：

• URL路径占位符未替换
  代码中请求地址里的{owner}、{repo}是文档示例的占位符，如果没有将这两个值替换为实际的仓库所有者用户名、目标仓库名称，API会因找不到对应资源路径直接返回404。另外要注意，路径中填写的目标文件名大小写必须和仓库内的实际文件名完全匹配，大小写不匹配同样会触发404错误。
• 鉴权配置缺失或权限不足
  GitHub Content API 属于受权限管控的接口，如果匿名发起请求、或者携带的访问令牌没有对应仓库的读写权限，API为了避免泄露私有仓库的存在性，不会返回“权限不足”的403状态码，而是统一返回404。
  解决方式：在请求头中添加合法的鉴权字段，格式为Authorization: token <你的有效个人访问令牌>，且申请的令牌需要勾选对应仓库的repo读写权限范围。
• 请求体格式不符合接口规范
  现有代码存在两处明显的格式问题，很容易导致接口返回异常：
  1. 已经通过btoa()完成Base64编码的文件内容，被多余的大括号包裹成了对象类型，不符合API要求的字符串入参格式
  2. 用于标记文件版本的sha字段值，同样被多余的大括号包裹成了对象，没有传入对应文件的字符串格式Blob哈希值
     正确的请求体构造参考：

  // 兼容中文、特殊字符的Base64编码逻辑，避免btoa直接编码报错
  const encodedContent = btoa(unescape(encodeURIComponent(rawContent)))
  const requestBody = {
    message: 'put method test',
    content: encodedContent,
    // 仅当更新仓库中已存在的文件时，才需要传入对应文件的最新sha值；新建文件时不需要传该字段
    ...(fileSha ? { sha: fileSha } : {})
  }
  

• 目标分支参数缺失
  默认情况下，Content API 只会操作仓库默认分支（如main、master）下的文件，如果目标文件存储在其他自定义分支下，未指定分支参数的请求会因找不到对应文件返回404。
  解决方式：如果需要操作非默认分支的文件，需要在请求URL末尾追加查询参数ref=目标分支名称。

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