必须配置Personal Access Token和User-Agent头，否则易触发401/403错误；需注意PHP版本兼容性（^3.5适配PHP 7.4–8.1）、分页参数per_page/page、速率限制及异常类型精准捕获。
直接用 composer require 安装 php-github-api/php-github-api 就能调用 GitHub API，但默认配置下容易 403、401 或返回空数据——根本原因是 GitHub 自 2021 年起强制要求所有 API 请求带 Authorization 头，且多数写操作（如创建 issue、push commit）必须用 Personal Access Token（PAT），不能用密码或基础认证。
安装时确认版本兼容 PHP 和 GitHub API v3
该库已停止维护（最后发布是 2022 年的 v3.5.0），但它仍稳定支持 GitHub REST API v3。不推荐拉 dev-main 或高版本分支，因为与 PHP 8.2+ 的类型声明冲突风险高。
执行以下命令即可：
composer require php-github-api/php-github-api:^3.5
注意检查你的 PHP 版本：
立即学习“PHP免费学习笔记（深入）”；
- PHP 7.4–8.1：用
^3.5安全 - PHP 8.2+：避免
^3.6及以上（存在ReturnTypeWillChange报错） - 若项目已用 Laravel，别用
laravel/socialite混搭——它不提供底层 API 调用能力，只是 OAuth 登录封装
初始化 Client 必须传入 token，且不能省略 user-agent
GitHub API 明确要求每个请求含 User-Agent 头，否则直接 403；未授权时返回 401，但错误信息极简（只有 {"message":"Bad credentials"}），容易误判为网络问题。
正确初始化方式：
$client = new \Github\Client();
$client->authenticate('ghp_xxx...', \Github\Client::AUTH_HTTP_TOKEN);
$client->setUserAgent('my-app-name/1.0'); // 必须设，值可任意但不能为空
常见错误：
- 漏掉
setUserAgent()→ 403 Forbidden，无提示原因 - 用
AUTH_URL_TOKEN（已废弃）→ 认证失败且不报错，后续调用静默返回空数组 - token 权限不足（比如只勾了
public_repo却想读 org secrets）→ 404 或 403，不是 401
调用 issues、repos 等接口时注意分页和速率限制
GitHub 默认每页最多 30 条，且未显式传 per_page 参数时就用这个值；rate_limit 剩余数藏在响应头里，不主动查会突然被限流（HTTP 403 + X-RateLimit-Remaining: 0）。
推荐写法：
// 获取前 100 个 issue（需分两页）
$issues = $client->api('issue')->all('owner', 'repo', ['state' => 'all', 'per_page' => 100, 'page' => 1]);
// 检查是否还有更多
$remaining = (int) $client->getHttpClient()->getLastResponse()->getHeader('X-RateLimit-Remaining')[0];
关键点：
- 所有列表接口（
api('repo')->all()、api('user')->repositories()）都支持per_page和page参数，但不支持limit这种 Laravel 风格参数 - 搜索接口（如
api('search')->repositories()）走的是另一套规则，q参数必须 URL 编码，且不支持字段级过滤（例如不能直接q=language:php stars:>100得手动拼） - 上传 release asset 用
api('repo')->releases()->assets()->upload()，但必须先拿到upload_url（含临时 token），不能直接 POST 到 releases 接口
调试时优先看响应头和异常类型，别只盯 body
这个库抛出的异常类型很具体，比 raw cURL 更易定位问题：
-
\Github\Exception\RuntimeException：网络超时、DNS 失败等底层错误 -
\Github\Exception\ErrorException：API 返回非 2xx 状态码（如 404 repo not found） -
\Github\Exception\BadCredentialsException：明确 token 错误或过期
建议加一层兜底日志：
try {
$data = $client->api('user')->show();
} catch (\Github\Exception\BadCredentialsException $e) {
error_log('GitHub token invalid or expired: ' . $e->getMessage());
} catch (\Github\Exception\ErrorException $e) {
error_log('GitHub API error ' . $e->getCode() . ': ' . $e->getMessage());
// 查看完整响应头
$headers = $client->getHttpClient()->getLastResponse()->getHeaders();
}
真正难排查的不是“调不通”，而是“调通了但数据不对”——比如用组织名当 owner 却没开 SSO 授权，或 token 没勾选 read:org 却去查 org 成员列表，此时返回空数组而非报错。
